Operator CLI—dashboard automation, BLXCKCHAT agent, Bible and public kingdom catalog reads
Unified operator control plane for the JEXXXUS ecosystem—in active development.
Marketing/landing page: cli.jexxx.us
Availability
The JEXXXUS CLI (jexxxus) is operator-only and not ready for end users. The repository is private today; open-source readiness (SECURITY.md, secret scanning, hardening) is in progress before any public GitHub release.
This page documents intended behavior for internal operators and kingdom architecture readers. It does not publish credentials, keys, connection strings, or backend implementation details.
Development status (July 2026): Operator commands (doctor, import, notify, auth) are stable. BLXCKCHAT—the native bring-your-own-key AI agent—is shipped in beta for operators: interactive terminal chat, public Bible/VEIL/TV lookups, dashboard diagnostics, and gated write tools. Kingdom-wide thematic replies (scripture + VEIL + JEXXXUS | TV in one answer) are in active refinement.
What It Is
A headless Node.js command-line tool that provides unified operator access to JEXXXUS dashboards and an operator-facing AI agent scoped to kingdom workflows.
Dashboard automation targets a shared MAMAbase (Supabase) that serves both the BLXCKBOOK relationship vault (api.contacts) and the NXT memory journal (public.vessels, public.contact_events). A --target flag routes commands to the appropriate schema, so the same CSV import flow works for both surfaces.
BLXCKCHAT (bare jexxxus, or jexxxus blxckchat) is the default entry point on the same binary: a bring-your-own-key natural-language agent for Bible lookups, public VEIL and JEXXXUS | TV catalog reads, connectivity checks, and—when confirmed—notifications and contact imports. It is not a general coding agent, does not browse the open web, and does not index internal vault documentation. Typing jexxxus with no arguments opens it directly; the full non-interactive command list (doctor, import, notify, auth, bible) is available via jexxxus shell or jexxxus --help.
The CLI is not a consumer feature on VEIL, TV, Law, or Docs surfaces. End-user chat lives at BLXCKCHAT (blxckchat.jexxx.us)—a different product that shares the brand.
Stack Applicability
| Surface | CLI role today | Notes |
|---|
| BLXCKBOOK | ✅ Primary | CSV → api.contacts bulk import (--target blxckbook) |
| NXT | ✅ Supported | CSV → public.vessels + public.contact_events (--target nxt) |
| MAMAbase | ✅ Write target | Shared Supabase; operator auth bypasses RLS |
| BLXCKCHAT | ✅ Native agent (BYOK) | jexxxus blxckchat—operator AI; not the web chat app |
| Bible | ✅ Read-only | jexxxus bible + BLXCKCHAT bible_query tool |
| VEIL | ✅ Read-only (public) | BLXCKCHAT veil_query—published articles on veil.jexxx.us only |
| **JEXXXUS \ | TV** | ✅ Read-only (public) | BLXCKCHAT tv_query—public watch catalog on tv.jexxx.us only |
| Docs | 📄 Reference + RAG | This page mirrors vault docs; BLXCKCHAT indexes public Docs content only |
| Law | — | No runtime dependency |
| wing6 | — | Infrastructure context only |
All JEXXXUS surfaces share the same Supabase project but isolate data by schema (api for BLXCKBOOK, public for NXT). The CLI respects this isolation through its --target routing and per-schema connectivity checks in doctor.
When to Use It
| Scenario | CLI fit |
|---|
| Migrating contacts from a spreadsheet | ✅—jexxxus import |
| Seeding a new vault account (one-time backfill) | ✅ |
| Verifying operator credentials before an import | ✅—jexxxus doctor |
| Pushing a notification to a user's bell | ✅—jexxxus notify |
| Scripture lookup from the terminal | ✅—jexxxus bible or BLXCKCHAT |
| Kingdom-themed research (scripture + VEIL + TV) | ✅—BLXCKCHAT interactive chat |
| Day-to-day contact edits | ❌—use BLXCKBOOK UI |
| VEIL article publishing | ❌—use Decap CMS or Obsidian sync |
| TV video uploads | ❌—use xdmin or upload flows |
| End-user encrypted chat | ❌—use BLXCKCHAT web app |
Command Overview
| Command | Purpose |
|---|
jexxxus doctor | Read-only MAMAbase connectivity check (one or both dashboards) |
jexxxus import <file> | Bulk CSV import into BLXCKBOOK or NXT |
jexxxus notify | Push a system notification to a user's dashboard bell |
jexxxus auth | End-user device login via secure.jexxx.us (scoped to signed-in account) |
jexxxus bible | Read-only Bible vault lookup (section, book, chapter, verse, query) |
jexxxus (bare) | Default. Native AI agent (BYOK)—interactive TUI or one-shot prompt |
jexxxus blxckchat | Same as bare jexxxus—explicit alias |
jexxxus blxckchat configure | Set up Anthropic, OpenAI, or local Ollama provider |
jexxxus shell | Print this command list without opening the agent (scripting) |
BLXCKCHAT—Native AI Agent
BLXCKCHAT gives operators a natural-language interface to JEXXXUS-specific functions. Configure once with jexxxus blxckchat configure; credentials are stored locally on the operator machine (mode 0600), never in public repos.
Usage
# One-time provider setup (API keys redacted in --list output)
jexxxus blxckchat configure
jexxxus blxckchat configure --list
# One-shot prompt (stateless—no memory between invocations)—bare or explicit
jexxxus "What does Genesis 1:1 say?"
# Interactive terminal chat (conversation persists within the session)
jexxxus
# Resume last autosaved session
jexxxus --resume
# Named provider config for this invocation
jexxxus blxckchat --provider my-ollama "run doctor"
# Opt in to shell access (off by default; every call still requires confirmation)
jexxxus blxckchat --shell
Providers (v1): Anthropic, OpenAI, and Ollama (local or cloud). Ollama needs no API key—only a reachable base URL.
Tools
BLXCKCHAT wraps existing CLI capabilities as agent tools rather than reimplementing them:
| Tool | Mode | Notes |
|---|
bible_query | read-only | Scripture lookup (same data as jexxxus bible) |
veil_query | read-only | Public VEIL articles on veil.jexxx.us |
tv_query | read-only | Public **JEXXXUS \ | TV** catalog on tv.jexxx.us |
run_doctor | read-only | Dashboard connectivity check |
send_notification | write, confirm | Wraps jexxxus notify—requires y/N approval |
import_contacts | write, confirm | Wraps jexxxus import—requires y/N approval |
account_query | read-only (RLS) | Signed-in user's vault, NXT, and TV playlists after jexxxus auth login |
run_shell | write, confirm, opt-in | Only when --shell is passed; regex blocklist (not a sandbox) |
Every write or shell tool call prompts the operator before execution—the model cannot bypass confirmation. Tool attempts are audited locally on the operator machine.
Context (RAG)
Each turn, BLXCKCHAT retrieves the most relevant sections from this public documentation site (docs.jexxx.us) using a local lexical index cached on the operator workstation. Internal operator vaults are never indexed by default. If documentation changes, the index rebuilds automatically when content hashes differ.
Kingdom/Garden content synthesis
For thematic questions—confession, church girls, named series, multi-surface story beats—BLXCKCHAT is designed to combine all relevant public surfaces in one reply: scripture verses, matching VEIL articles, and JEXXXUS | TV watch recommendations with canonical public URLs. Short follow-ups ("keep going") inherit recent conversation context so persona scenes stay coherent.
Public catalogs expose titles, descriptions, and watch-page links only—never private stream or embed URLs.
Divinities personas
Operators can activate curated persona voices in interactive chat via /divinities (filterable picker) or /divinities <name>. Personas change voice and system instructions; BLXCKCHAT tools remain available. Activating a persona starts a fresh in-session voice. Persona libraries are operator-local and are not merged into the public Docs RAG index.
Safety model
- Not a coding agent—no arbitrary file read/write, no open-web browsing
- Shell access is off unless
--shell is explicitly passed - Even with shell enabled, a regex blocklist rejects common destructive patterns before confirmation—but shell runs via
/bin/sh -c, so treat --shell as a trusted-operator feature, not a sandbox - Streaming replies use plain text during generation; formatted links appear on the final message to avoid terminal garble
Bible Lookup (jexxxus bible)
Read-only access to the JEXXXUS Bible reference library (same source that powers bible.jexxx.us content workflows).
jexxxus bible section # list major sections
jexxxus bible book <section> # list books in a section
jexxxus bible chapter <section> <book> # list chapters
jexxxus bible verse <book> <chapter> <verse> # single verse
jexxxus bible query "Genesis 1:1" # natural-format query
jexxxus bible query "1 Samuel 2:1" # numbered books supported
Operators need a local Bible vault checkout or a configured vault path on the workstation. BLXCKCHAT's bible_query tool uses the same lookup layer.
System Notifications
The notify command pushes free-form operator messages into a user's notification bell in both BLXCKBOOK and NXT. Notifications appear in real-time (via Supabase Realtime) without requiring a page refresh.
Usage
jexxxus notify -u <clerkUserId> -m "Your tier unlocked! 🎉" -y success
Options:
-u, --user <clerkUserId>—recipient's Clerk user ID (required)-m, --message <text>—notification message (required)-y, --type <type>—message type: info (default), success, warning, or error
Examples:
# Info notification (blue dot)
jexxxus notify -u user_2Fk3L9xZ -m "New feature deployed"
# Success notification (green dot)
jexxxus notify -u user_2Fk3L9xZ -m "Tier unlocked!" -y success
# Warning notification (amber dot)
jexxxus notify -u user_2Fk3L9xZ -m "Your free tier expires soon" -y warning
# Error notification (red dot)
jexxxus notify -u user_2Fk3L9xZ -m "Account sync failed" -y error
Behavior
- Notifications are written to the shared
public.system_notifications table in MAMAbase - Both dashboards subscribe to Realtime changes on this table
- Users see the notification in their bell within 1–2 seconds (no polling required)
- Recipients can dismiss notifications; dismissed state is stored in the database
- The bell shows a count of all unread notifications (contacts added, event invites, and system notifications combined)
Who Can Send
Only operators with CLI credentials can send notifications. End users cannot generate system notifications via the app—this is an operator-only feature.
Data Flow
Operator workstation (private checkout)
│
├─► jexxxus doctor
│ │
│ ├─ api.contacts (BLXCKBOOK)
│ └─ public.vessels + public.contact_events (NXT)
│
├─► jexxxus import contacts.csv --user <clerk_user_id> [--target blxckbook|nxt]
│ │
│ ├─► --target blxckbook ──► MAMAbase—api.contacts ──► BLXCKBOOK app
│ └─► --target nxt ──► MAMAbase—public.vessels ──► NXT dashboard
│
└─► jexxxus blxckchat
│
├─► RAG: docs.jexxx.us (public content only)
├─► bible_query / veil_query / tv_query (read-only public catalogs)
└─► send_notification / import_contacts (confirmed writes)
The CLI runs headless with operator-only database credentials that bypass Row Level Security. Every import must set --user to the Clerk user ID that should own the rows. A wrong or missing owner creates rows invisible to the intended vault account.
Schema isolation: BLXCKBOOK data lives in api.contacts (the api schema). NXT data lives in public.vessels and public.contact_events (the public schema). Both tables share the same Supabase project and require the same operator credentials. The CLI routes to the correct schema based on --target.
CSV Format
| Column | Required | Notes |
|---|
Name | Yes | Display name |
Notes or Bio | No | Free-text notes |
Tags or Interests | No | Comma-separated list |
Example:
Name,Notes,Tags
Alex Rivera,Met at conference,"friend, tech"
Jordan Lee,,
Legacy header aliases (Bio, Interests) map to notes and tags.
End-User Authentication (jexxxus auth)
End users can authenticate the CLI against their own JEXXXUS account via secure.jexxx.us, a dedicated Clerk auth gateway—separate from the jexxx.us landing site so it can grow into a general-purpose account/auth surface without being tied to CLI-specific routing.
This is additive to, not a replacement for, the CLI's existing operator-scoped credentials (local .env)—those remain for batch imports and other tooling that must bypass RLS entirely. jexxxus auth is the path for a signed-in end user's own commands to run scoped to their own account.
Commands
| Command | Purpose |
|---|
jexxxus auth login | Starts the device authorization flow—prints a verification URL + short code, opens the default browser if possible, polls until you approve or deny in the browser |
jexxxus auth status | Shows the signed-in email, user ID, and token expiry |
jexxxus auth refresh | Manually refreshes the access token (also happens automatically when a token is near expiry) |
jexxxus auth logout | Revokes and securely deletes stored credentials |
How it works
jexxxus auth login generates a PKCE code pair locally and registers the challenge with secure.jexxx.us, getting back a short user-facing code (e.g. ABCD1234)- It prints
https://secure.jexxx.us/auth/cli?code=ABCD1234 and attempts to open it in your browser - You sign in via Clerk (if not already) and see a consent screen: "JEXXXUS CLI wants permission to access your JEXXXUS account"—confirm the code matches your terminal, then Allow or Deny
- The CLI, which has been polling in the background, receives a durable refresh token and an immediate access token once you approve
- Credentials are stored in
~/.jexxxus/credentials.json (mode 0600)
The access token is a real Clerk session JWT, minted server-side by secure.jexxx.us on your behalf—the same token shape Supabase already verifies for RLS across BLXCKBOOK and NXT. Refreshing doesn't require the browser: the CLI presents its stored refresh token to secure.jexxx.us, which mints a fresh JWT against your still-active Clerk session.
If you revoke the CLI's access (or your Clerk session expires/is revoked elsewhere), jexxxus auth refresh will fail and prompt you to run jexxxus auth login again.
Operator Setup (Private Checkout)
git clone git@github.com:blxckbooklabs/jexxx.us-cli.git
cd jexxx.us-cli
npm install && npm run build && npm link
Copy .env.example to .env and fill in values from managed operator secret storage—never commit .env, never paste keys into Docs, Law, or public repos.
jexxxus doctor
jexxxus import ./contacts.csv --user user_2xxxxxxxx
jexxxus blxckchat configure
jexxxus blxckchat
| Command / flag | Purpose |
|---|
doctor | Verify credentials + MAMAbase reachability across all schemas (no writes) |
doctor --target blxckbook | BLXCKBOOK-only (api.contacts) connectivity check |
doctor --target nxt | NXT-only (public.vessels + public.contact_events) connectivity check |
import <file> --target blxckbook | Import CSV into BLXCKBOOK api.contacts (default) |
import <file> --target nxt | Import CSV into NXT public.vessels |
-u, --user <id> | Vault owner Clerk user ID (required for production imports) |
-f, --force | On duplicate-key errors, insert remaining rows one-by-one and skip duplicates |
--allow-system-user | Dev/test only—permit default SYSTEM owner |
notify -u <id> -m <msg> | Push a system notification to a user's bell in both dashboards (Realtime) |
-y, --type <type> | Notification type: info (default), success, warning, or error |
blxckchat configure | Set up BYOK provider (Anthropic, OpenAI, Ollama) |
blxckchat --resume | Resume last autosaved BLXCKCHAT session |
blxckchat --shell | Opt in to shell tool for this session (off by default) |
Security Posture
- Operator credentials stay on operator machines and in secret managers—never in public documentation
- BLXCKCHAT indexes public Docs content only—internal vaults are excluded by design
- Public VEIL and JEXXXUS | TV tools return published catalog metadata and canonical URLs only—no private stream paths or admin surfaces
- Imports are audited by
user_id ownership; default SYSTEM is blocked unless explicitly overridden for dev - The CLI does not log connection strings, JWT material, or full database error payloads
- BLXCKCHAT write and shell tools require interactive confirmation; shell blocklist is defense-in-depth only
- Operator repo includes
SECURITY.md (vulnerability reporting, credential tiers, pre-public checklist) - Public sites (Docs, Law, VEIL, TV) describe behavior only—never paste keys or connection strings here
Robustness Notes
- Automated test suites cover CSV import, auth, BLXCKCHAT agent loop, kingdom/garden routing, URL sanitization, VEIL/TV public-read security boundaries, and terminal UI behavior (
npm test in the private repo) - Validates non-empty
Name before insert; skips invalid rows with a warning - Exits non-zero on parse failures, missing files, auth misconfiguration, or total import failure
- Duplicate handling: without
--force, the batch aborts on the first constraint violation; with --force, duplicates are skipped individually - BLXCKCHAT normalizes tool arguments for smaller local models and short-circuits repeated identical tool calls
Related