title: "Reference: vox CLI (minimal compiler binary)" description: "Official documentation for Reference: vox CLI (minimal compiler binary) for the Vox language. Detailed technical reference, architectur" category: "reference" last_updated: 2026-03-24 training_eligible: true

Reference: vox CLI (minimal compiler binary)

The vox executable is built from crates/vox-cli (repository root). This page documents the commands that exist in that crate today. Other markdown pages may describe a broader future or workspace-wide toolchain (Mens, review, MCP, etc.) — those are not necessarily linked into this binary yet.

Global flags, completions, Latin groupings

• Global (before subcommand): --color auto|always|never (see NO_COLOR), --json (sets VOX_CLI_GLOBAL_JSON for subcommands that support machine JSON), --verbose / -v (if RUST_LOG is unset, tracing uses debug), --quiet / -q (VOX_CLI_QUIET).
• Completions: vox completions bash | zsh | fish | powershell | elvish — print to stdout and install per your shell (e.g. bash: vox completions bash > /path/to/bash_completion.d/vox).
• Dynamic command catalog: vox commands — clap-derived list from the actual compiled binary; add --recommended for first-time essentials or --format json --include-nested for tooling.
• Secrets namespace: vox clavis (alias vox secrets) centralizes token health checks and credential compatibility storage.
• Latin aliases (same behavior as flat commands): vox fabrica (fab) — build/check/test/run/dev/bundle/fmt/script; vox diag — doctor, architect, stub-check; vox ars — snippet, share, skill, openclaw, ludus; vox recensio (rec, feature coderabbit) — same as vox review.

Product lanes

The command registry also carries a separate product_lane value used for bell-curve planning and discoverability. This is not a CLI rename and does not replace latin_ns.

Package management (vox-pm)

Project dependencies are declared in Vox.toml, locked in vox.lock, and materialized under .vox_modules/. This is separate from vox upgrade, which refreshes the Vox toolchain (never edits Vox.toml / vox.lock): either a release binary or a local git checkout + source install.

Rust crate imports declared in .vox files (import rust:<crate> ...) are compiled into generated Cargo.toml dependencies. vox.lock remains the high-level Vox dependency contract; Cargo.lock is generated by Cargo at build time from the emitted manifest.

Explicit advanced verbs (registry parity): vox pm search, vox pm info, vox pm publish, vox pm yank, vox pm vendor, vox pm verify, vox pm mirror (--file or --from-registry), vox pm cache status, vox pm cache clear.

Git-source note: vox sync and vox pm verify do not fetch/verify git payloads in-repo yet. They fail fast by default; for explicit operator bypass in controlled environments set VOX_PM_ALLOW_GIT_UNVERIFIED=1.

Removed: the old vox install package verb — use vox add, vox lock, vox sync, and vox pm instead (vox install is an unrecognized subcommand).

Migration note (old → new verbs): pm-migration-2026.md.

Design rules and registry parity: cli-design-rules-ssot.md, command-compliance.md. Generated command table: cli-command-surface.generated.md (vox ci command-sync --write).

Environment variables: canonical names and precedence — reference/env-vars.md (alias: ref/env-vars.md).

Build & run

vox build <file>

Compile a .vox source file.

Also writes generated Rust under target/generated/ (backend crate). If the module declares @v0 UI components and output files are missing, the CLI invokes Vercel's npx v0 add sidecar process.

vox island … (feature island)

Not in default builds. cargo build -p vox-cli --features island (often add default stack: e.g. --features island,mens-base if you used --no-default-features).

First run: if islands/package.json is missing, generate, upgrade, add, and the build step bootstrap a minimal Vite + React tree under islands/ (then pnpm install / pnpm run build). Requires pnpm on PATH (same as vox run’s frontend step). Use --no-build on generate/upgrade to skip the Vite build.

vox generate (HTTP inference) vs MCP codegen

Top-level vox generate (crates/vox-cli/src/commands/generate.rs) posts to a local HTTP inference server (default http://127.0.0.1:7863/generate). It is intentionally narrow: QLoRA / playground style validation loops without requiring MCP.

vox_generate_code (and related MCP chat tools) use the workspace orchestrator + Codex path: model registry / Ludus routing, optional workspace journey DB, structured transcripts with journey-envelope.v1, and routing_decisions rows. The CLI HTTP path does not silently provide the same joins — use MCP when you need that unified telemetry story. A later optional bridge (for example an explicit MCP-backed codegen flag) would make the difference obvious in UX.

vox run <file> [-- <args>…]

1. Runs the same pipeline as build (output to dist/).
2. If .tsx files are present under dist/, scaffolds a Vite app, runs pnpm install / pnpm run build, and copies assets into target/generated/public/.
3. Runs cargo run -- <args> in target/generated.

Backend listens on the port from VOX_PORT (or 3000) — same variable the generated main.rs reads.

pnpm workspace (repo root): when the scaffold wrote pnpm-workspace.yaml at the repository root (for example islands/ plus dist/.../app), run pnpm install once from that root so workspace packages link correctly, then use per-package pnpm run build / pnpm run dev as needed. See tanstack-web-backlog.md Phase 3.

vox script <file> [-- <args>…] (feature script-execution)

Not in default builds. Same script runner as vox run --mode script, with explicit flags: --sandbox, --no-cache, --isolation, --trust-class. Build: cargo build -p vox-cli --features script-execution.

When VOX_MESH_ENABLED=1 and the binary is built with --features populi (pulls in vox-populi; optionally combine with script-execution), vox script / script-mode vox run best-effort publishes a node record to the local registry file (see mens SSOT).

vox populi … (feature populi)

Not in default builds. One-command private mesh lifecycle helpers backed by the same Populi control plane. Build: cargo build -p vox-cli --features populi.

Optional NVML-backed GPU inventory on join/heartbeat NodeRecords (ADR 018 Layer A): add mesh-nvml-probe (e.g. cargo build -p vox-cli --features populi,mesh-nvml-probe). Requires NVIDIA driver/NVML at runtime; see GPU truth probe spec.

Interpreted vox mens workflow run (journal + mesh_* activity hooks; there is no top-level vox workflow) requires --features workflow-runtime (implies mens-dei + vox-workflow-runtime). The runtime emits versioned journal events (journal_version: 1) and durable rows keyed by a run id plus activity_id. Use --run-id <id> to resume the same interpreted workflow run; omit it to start a fresh run id. The interpreted runner can replay stored step results for linear workflows. Mens steps use env-derived VOX_MESH_CONTROL_ADDR / Vox.toml [mens] only — use with { timeout: …, retries: …, initial_backoff: …, activity_id: …, id: …, mens: "noop" | "join" | "snapshot" | "heartbeat" } on mesh_* calls (id is an alias for activity_id). Retry/backoff support currently applies to interpreted mesh_* activity execution; other interpreted activities remain journal-only no-ops. Codex append is enabled by default when DB config resolves and can be disabled with VOX_WORKFLOW_JOURNAL_CODEX_OFF=1 (orchestration SSOT, durable execution).

vox ci …

Repository guards (manifest lockfile, docs/Codex SSOT, vox-cli feature matrix, doc inventory, milestone eval matrix contract, workflow scripts/ allowlist, Mens gate matrix, TOESTUB scoped scan, optional CUDA checks). Canonical: vox ci <subcommand> when vox is on PATH. CI/bootstrap: cargo run -p vox-cli --quiet -- ci <subcommand> from the repo root (same code path).

Bootstrap / dev launcher (missing vox on PATH)

When vox is not installed or not on PATH, use the repo launchers so cargo run -p vox-cli runs from the workspace root (Cargo decides incrementally whether to rebuild):

• Windows (PowerShell): pwsh -File scripts/windows/vox-dev.ps1 <vox args…> — scripts/windows/vox-dev.ps1
• Linux / macOS / Git Bash: ./scripts/vox-dev.sh <vox args…> — scripts/vox-dev.sh

Full-repo CodeRabbit (build-if-needed + open PRs): set GITHUB_TOKEN or GH_TOKEN, then from the repo root:

pwsh -File scripts/windows/vox-dev.ps1 review coderabbit semantic-submit --full-repo --execute

./scripts/vox-dev.sh review coderabbit semantic-submit --full-repo --execute

Equivalent one-liner without the script: cargo run -p vox-cli --features coderabbit -- review coderabbit semantic-submit --full-repo --execute (plan-only: omit --execute).

vox clavis (alias vox secrets)

Centralized secret diagnostics and compatibility credential storage.

vox repo

Repository discovery from the current directory (vox repo with no subcommand defaults to status) plus explicit multi-repo catalog tools under .vox/repositories.yaml. Catalog query commands are read-only and treat remote repositories as adapter descriptors unless a later backend is configured.

vox init

Scaffolds Vox.toml, src/main.vox, .vox_modules/, or a <name>.skill.md file (same layout as MCP vox_project_init; success JSON schema vox-project-scaffold-result.schema.json). Implementation: vox-project-scaffold crate (shared with vox-mcp).

Deprecated compatibility commands

• vox login [--registry <name>] [<token>] [--username <name>] — compatibility shim for older workflows; prefer vox clavis set.
• vox logout [--registry <name>] — compatibility shim; prefer vox clavis commands.

Diagnostics: vox lock-report remains separate (lock telemetry); it is not part of the vox ci surface.

vox commands

Generate a dynamic command catalog from clap (VoxCliRoot::command()), so the list always matches what this binary actually exposes.

Why this exists: it is the discoverability source for first-timers, editor integrations, and docs/CI parity checks.

vox dev <file>

Watch mode: spawns vox-compilerd (JSON lines on stdio; one DispatchRequest per process), sends a dev request with file, out_dir, port, and open, then streams daemon output until exit or Ctrl+C. Resolve the daemon the same way as other compilerd tools: sibling to the vox executable, then PATH.

Build the daemon from this repo: cargo build -p vox-cli --bin vox-compilerd → target/debug/vox-compilerd(.exe) (install next to vox or add to PATH).

vox live

Terminal dashboard subscribed to an in-process vox-orchestrator event bus (demo / local use). Not in default builds: cargo build -p vox-cli --features live then run vox live.

Set VOX_ORCHESTRATOR_EVENT_LOG to a file path to tail the same JSONL stream vox-mcp appends when that variable is set (shared runtime view across MCP and CLI).

vox bundle <file>

End-to-end shipping flow: build → scaffold dist/app (Vite + React) → pnpm install + pnpm run build → copy static assets → cargo build on the backend → copy the resulting binary into dist/<stem> (plus .exe on Windows when applicable).

If no TSX components are detected after build, stops after codegen (“backend-only”).

vox migrate web

Automated codemod runner for migrating legacy web concepts into standardized Path C React syntax. vox migrate web --apply rewrites .vox files in place to remove legacy tags such as @component and updates them to standard block properties.

Quality

vox check <file>

Lex, parse, and type-check only. Prints diagnostics to stderr; exits with error if any error-severity diagnostic exists.

• --emit-training-jsonl <PATH>: append successful frontend records to JSONL for training corpus generation.

vox test <file>

Runs build, then cargo test in target/generated.

vox fmt <file>

Formats a .vox file using vox_compiler::fmt::try_format: parse → pretty-print → re-parse (fail-closed). Writes in place via a temp file + rename (see commands/fmt.rs). --check: exit non-zero if the file would change (CI-friendly). Constructs the formatter cannot print yet surface as parse errors once the printer/AST diverges; expand coverage in vox-compiler fmt/ over time.

vox doctor

Canonical path (English): vox doctor … — this is the primary spelling in docs, scripts, and muscle memory.

Grouped Latin path: vox diag doctor … — identical behavior; diag is the registry latin_ns bucket for diagnostics (see Nomenclature migration map). Prefer vox doctor in new prose; use vox diag doctor when teaching the Latin lane.

Development environment checks (Rust/Cargo, Node/pnpm, Git, optional Docker/Podman, Vox.toml, Codex workspace registration, API keys, etc.). With VOX_WEB_TS_OUT set to your vox build TypeScript output directory, doctor also verifies @v0 components use named exports for TanStack routes { (see env-vars.md).

Build: cargo build -p vox-cli --features codex for the extended path.

Tooling

vox db

Local VoxDB inspection and research helpers (crates/vox-cli/src/commands/db.rs, db_cli.rs). Uses the same connection resolution as Codex (VOX_DB_*, compatibility VOX_TURSO_*, legacy TURSO_*, or local path).

vox db audit prints read-only JSON to stdout: schema version, database paths, select storage PRAGMAs, and per-user-table row counts. Add --timestamps for heuristic MIN/MAX on a chosen time-like column per table (extra queries).

vox db prune-plan prints JSON counts for rows that match automated rules in contracts/db/retention-policy.yaml (days, ms_days, expires_lt_now). vox db prune-apply --i-understand runs the matching DELETEs. Rationale, sensitivity classes, and table notes (including ci_completion_*) live in telemetry-retention-sensitivity-ssot.

Common subcommands { status, audit, schema, sample, migrate, export / import, vacuum, pref-get / pref-set / pref-list, plus research flows (research-ingest-url, research-list, capability-list, …). Publication operator controls: publication-discovery-scan, publication-discovery-explain, publication-transform-preview, publication-route-simulate, publication-publish, and publication-retry-failed accept --json for structured stdout. publication-publish enforces the same live gate as other surfaces when --dry-run is off: VoxDb with two digest approvers and VOX_NEWS_PUBLISH_ARMED=1 (or orchestrator publish_armed is not read by this path); successful live runs update manifest state to published / publish_failed like MCP/orchestrator. Run vox db --help for the full tree.

Discovery/data-prep operator commands: vox db publication-discovery-scan, vox db publication-discovery-explain, vox db publication-transform-preview, and vox db publication-discovery-refresh-evidence. publication-discovery-explain JSON adds assist-only impact_readership_projection (not a publish gate) when scientia_novelty_bundle is present on the manifest. Prior-art / worthiness operator JSON: vox db publication-novelty-fetch (federated OpenAlex/Crossref/Semantic Scholar bundle; optional --persist-metadata; query limits/tunables from contracts/scientia/impact-readership-projection.seed.v1.yaml), vox db publication-decision-explain (Socrates/sidecar enrich + heuristic preflight + worthiness + discovery rank; optional --live-prior-art; includes the same assist-only projection when a novelty bundle is available), and vox db publication-novelty-happy-path (prior art + enrich + stdout: finding-candidate + bundle + merged rank + worthiness + calibration_telemetry + assist-only impact_readership_projection).

vox db mirror-search-corpus mirrors markdown into the Codex search corpus (delegates to the same implementation as vox scientia mirror-search-corpus).

vox telemetry

Optional operator upload path — not default-on, not product telemetry. Local JSON spool under .vox/telemetry-upload-queue (or VOX_TELEMETRY_SPOOL_DIR), explicit vox telemetry upload, secrets via Clavis (VOX_TELEMETRY_UPLOAD_URL, VOX_TELEMETRY_UPLOAD_TOKEN). Subcommands: vox telemetry status, vox telemetry export, vox telemetry enqueue --json <file>, vox telemetry upload (--dry-run supported). See ADR 023, telemetry remote sink spec, env-vars.

vox scientia

Typing / ergonomics: Publication subcommands are long on purpose—they are stable for scripting and match command-registry.yaml / vox ci command-compliance. Mitigations { vox completions <shell> (tab-complete partial subcommand paths); repeat operators may use shell aliases or wrappers. There is no separate Latin umbrella for scientia today; use English vox scientia … only.

Vox Scientia — facade over Codex research and publication workflows.

• Research/capability helpers: capability-list, research-list, research-map-list, retrieval-status, research-refresh, vox scientia finding-candidate-validate --json <path>, vox scientia novelty-evidence-bundle-validate --json <path>, and vox scientia mirror-search-corpus (same behavior as vox db mirror-search-corpus).
• Scientific publication lifecycle:
  • vox scientia publication-discovery-scan --publication-id <id> [--max-items <n>] [--source <name>] [--dry-run] [--json] (run publication discovery enrichment and queue candidate evidence before downstream readiness/submit flows)
  • vox scientia publication-discovery-explain --publication-id <id> [--max-items <n>] [--json] (inspect discovery scoring/ranking evidence for a publication without mutating submission state)
  • vox scientia publication-novelty-fetch --publication-id <id> [--persist-metadata] [--offline] [--json] (prior-art bundle; mirrors vox db publication-novelty-fetch)
  • vox scientia publication-decision-explain --publication-id <id> [--json] (preflight + worthiness + discovery rank; mirrors vox db publication-decision-explain)
  • vox scientia publication-novelty-happy-path --publication-id <id> [--offline] [--json] (candidate + bundle + rank + worthiness + calibration snapshot; mirrors vox db publication-novelty-happy-path)
  • vox scientia publication-transform-preview --publication-id <id> [--channel <name>] [--json] (render a dry-run preview of channel-specific transformed copy prior to live publish)
  • vox scientia collection-transform-preview --collection-id <id> [--channel <name>] [--json] (preview transformed channel output for collection-level syndication before publish orchestration)
  • vox scientia publication-prepare --publication-id <id> --author <name> [--title <title>] [--scholarly-metadata-json <file>] [--eval-gate-report-json <file>] [--benchmark-pair-report-json <file>] [--human-meaningful-advance] [--human-ai-disclosure-complete] [--preflight] [--preflight-profile default|double-blind] <path.md> (title defaults from markdown frontmatter/first heading; structured evidence seeds metadata_json.scientia_evidence with discovery signals and draft-prep hints)
  • vox scientia publication-prepare-validated (same flags as prepare except preflight is always on)
  • vox scientia publication-preflight --publication-id <id> [--profile default|double-blind] [--with-worthiness] (returns readiness findings plus manual_required and ordered next_actions)
  • vox scientia publication-zenodo-metadata --publication-id <id> (stdout JSON for Zenodo deposit metadata; no HTTP)
  • vox scientia publication-openreview-profile --publication-id <id> (stdout JSON: merged OpenReview invitation/signature/readers + API base; no HTTP)
  • vox scientia publication-worthiness-evaluate [--contract-yaml <path>] --metrics-json <path> (stdout worthiness decision JSON from repo contract + metrics file; no DB)
  • vox scientia publication-approve --publication-id <id> --approver <identity>
  • vox scientia publication-submit-local --publication-id <id>
  • vox scientia publication-status --publication-id <id> [--with-worthiness] (includes the embedded default preflight report so status doubles as the operator checklist surface; --with-worthiness adds the worthiness rubric to that same report)
  • vox scientia publication-scholarly-remote-status --publication-id <id> [--external-submission-id <id>] (poll remote scholarly repository / deposit state for a stored submission)
  • vox scientia publication-scholarly-remote-status-sync-all --publication-id <id> (poll remote status for every scholarly_submissions row on that publication)
  • vox scientia publication-scholarly-remote-status-sync-batch [--limit <n>] [--iterations <n>] [--interval-secs <s>] [--max-runtime-secs <s>] [--jitter-secs <s>] (batch sync across publications ranked by recent submission activity; optional bounded loop for supervised workers)
  • vox scientia publication-scholarly-staging-export --publication-id <id> --output-dir <dir> --venue zenodo|open-review|arxiv-assist (write venue-scoped scholarly staging artifacts under output-dir and validate layout; Zenodo adds zenodo.json, arXiv assist adds arxiv_handoff.json, main.tex stub, and arxiv_bundle.tar.gz; mirrors vox db publication-scholarly-staging-export)
  • vox scientia publication-scholarly-pipeline-run --publication-id <id> [--preflight-profile default|double-blind|metadata-complete] [--dry-run] [--staging-output-dir <dir> --venue zenodo|open-review|arxiv-assist] [--adapter <kind>] [--json] (default scholarly happy path: preflight → dual-approval gate → optional staging export → scholarly submit unless --dry-run; --json = compact single-line JSON on stdout; mirrors vox db publication-scholarly-pipeline-run)
  • vox scientia publication-arxiv-handoff-record --publication-id <id> --stage <staging-exported|…|published> [--operator <id>] [--note <text>] [--arxiv-id <id>] (append-only operator milestone for arXiv assist; published requires --arxiv-id)
  • vox scientia publication-external-jobs-due [--limit <n>] (list external submission jobs due for retry/tick)
  • vox scientia publication-external-jobs-dead-letter [--limit <n>] (list terminal failed external submission jobs)
  • vox scientia publication-external-jobs-replay --job-id <id> (requeue one dead-letter job to queued)
  • vox scientia publication-external-jobs-tick [--limit <n>] [--lock-ttl-ms <ms>] [--lock-owner <id>] [--iterations <n>] [--interval-secs <s>] [--max-runtime-secs <s>] [--jitter-secs <s>] (advance external submission worker queue; optional repeated ticks)
  • vox scientia publication-external-pipeline-metrics [--since-hours <h>] (read-only JSON rollup: jobs, attempts, snapshots, scholarly rows, publication_attempts by channel; mirrors vox db publication-external-pipeline-metrics)

Connection resolution matches vox db (VOX_DB_*, …). The publication flow uses digest-bound dual approvals before scholarly submission. For architecture/lingo and multi-platform routing internals, see docs/src/architecture/voxgiantia-publication-architecture.md.

vox shell

PowerShell-first guardrails for autonomous IDE terminals (see AGENTS.md): prefer pwsh on every host where it is installed. CI workflows may still use bash on Linux runners (docs/src/ci/runner-contract.md); that does not change the local/agent shell doctrine.

Boundaries: Vox does not ship a shell emulator product. See Vox shell operations boundaries.

Which surface to use

• vox shell repl — dev-only micro-REPL: built-in pwd / ls / cat (Rust; not PowerShell). Unknown lines are forwarded with split_whitespace → OS spawn (no quotes, pipes, redirection, or session cd). The first passthrough prints a stderr note describing those limits. Prefer pwsh for real shell work. Bare vox shell defaults to repl.
• vox shell check --payload "<ps>" — runs Parser::ParseInput via contracts/terminal/pwsh_extract_command_asts.ps1 and enforces contracts/terminal/exec-policy.v1.yaml. Optional --policy <path> overrides the default policy file.

Compact PowerShell lexicon (host terminal / vox shell check allowlist; not the repl):

Optional IDE wiring: .vscode/settings.json adds terminal profiles Vox Exec policy (PSReadLine) (loads .agents/workflows/vox_interceptor_profile.ps1) and Vox pwsh proxy (check only) (.vox/bin/vox-pwsh-proxy.cmd — set VOX_SHELL_CHECK_PAYLOAD to the line to validate). See also terminal-ast-validation-research-2026.md.

vox codex

Codex (Turso / Arca) utilities backed by vox-db.

vox codex cutover automates legacy-chain migration: exports JSONL + a JSON sidecar, creates a new local SQLite file at --target-db, imports, and prints the VOX_DB_PATH you should export next. Requires a local legacy file (--source-db or configured VOX_DB_PATH). Use --force only after backing up an existing target path.

Connection uses DbConfig::resolve_standalone() (VOX_DB_*, VOX_TURSO_*, legacy TURSO_*, or local path).

Always available in the minimal binary. vox snippet — save, search, and export use the local Codex database (VOX_DB_URL / VOX_DB_TOKEN or .vox/store.db). vox share — publish, search, list, review against the same index.

vox skill (feature ars)

Not in default builds. cargo build -p vox-cli --features ars. Subcommands mirror the ARS helpers: list, install, uninstall, search, info, create, eval-task, promote, run, context-assemble, discover (see commands::extras::ars).

vox ludus (feature extras-ludus)

Not in default builds. cargo build -p vox-cli --features extras-ludus. Companions, quests, shop, arena, collegium, etc. (commands::extras::ludus). Terminal HUD: vox ludus hud requires --features ludus-hud (implies extras-ludus + vox-orchestrator).

vox stub-check (feature stub-check)

Not in default builds. cargo build -p vox-cli --features stub-check. Runs TOESTUB (vox-toestub) over a directory tree, with optional Codex persistence (baselines, task queue, suppressions) and Ludus rewards on a clean run (vox-ludus).

CI / parity: prefer vox ci toestub-scoped (default scan root crates/vox-repository) — same policy surface as GitHub Actions. Use vox stub-check … for interactive or repo-wide scans when you need clap flags (format, baselines, Ludus, etc.). Optional thin shell: scripts/quality/toestub_scoped.sh delegates to vox ci toestub-scoped; the standalone toestub crate binary remains available for advanced tooling.

toestub binary (crate vox-toestub): besides --mode, --format, --canary-crates, and --suppressions, the rollout surface includes --tests-mode (off | include | strict, default off — skips noisy unresolved-ref under .../tests/... when off), --prelude-allowlist (JSON per contracts/toestub/prelude-allowlist.v1.json), and --feature-flags (comma-separated, e.g. unwired-graph, scaling-fs-heuristic-fallback).

vox architect (features stub-check or codex)

Not in default builds. Requires cargo build -p vox-cli --features stub-check and/or --features codex (same feature gates as commands::diagnostics). Subcommands: check (workspace layout vs vox-schema.json), fix-sprawl (--apply to move misplaced crates), analyze (optional path, default . — god-object scan via TOESTUB; needs --features stub-check; with codex only, the command is available but analyze exits with a hint to add stub-check). Implementation: crates/vox-cli/src/commands/diagnostics/tools/architect.rs.

vox openclaw (feature ars)

Not in default builds. Build with cargo build -p vox-cli --features ars, then run vox openclaw (alias oc). Vox resolves endpoints from explicit flags, env/Clavis, and upstream discovery (/.well-known/openclaw.json) with cache fallback. Subcommands include import, list-remote, vox openclaw search-remote <query>, config (prints resolved HTTP/WS/catalog/discovery source), vox openclaw doctor (health + optional sidecar autostart), MCP-backed approvals / approve / deny, WS-backed subscribe / unsubscribe / subscriptions / notify (JSON-capable), and vox openclaw gateway-call --method <name> --params-json '{...}' for direct WS method invocation. Sidecar lifecycle is also exposed via vox openclaw sidecar status, vox openclaw sidecar start, and vox openclaw sidecar stop (state-backed PID lifecycle). serve expects a vox-gateway binary on PATH. SSOT: openclaw-discovery-sidecar-ssot.md.

vox lsp

Spawns the vox-lsp binary (from the vox-lsp crate) with stdio inherited. Ensure vox-lsp is on PATH (e.g. cargo build -p vox-lsp and use target/debug).

Mens / DeI (feature-gated)

Normative semantics (defaults, train / merge / serve matrix, data-prep SSOT, deferred trainer flags): reference/mens-training.md. This section lists CLI surfaces and build features only; do not treat it as a second SSOT for training behavior.

Doc parity (vox ci command-compliance): vox mens corpus, vox mens pipeline, vox mens status, vox mens watch-telemetry (alias vox mens watch; tails stderr + training JSONL ~3s), vox mens plan, vox mens eval-gate, vox mens bench-completion, vox mens system-prompt-template, vox mens train (GPU / Candle QLoRA; same intent as vox-mens shim (vox mens …)), vox oratio, vox mens serve, vox mens probe, vox mens merge-weights, vox mens merge-qlora, vox mens eval-local, vox mens generate, vox mens review, vox mens check, vox mens fix, vox mens workflow list, vox mens workflow inspect, vox mens workflow check, vox mens workflow run.

With default features (mens-base only — corpus + vox-runtime, no Oratio / vox-oratio and no native training deps), vox mens covers corpus / pipeline / status / plan / eval-gate / bench-completion / system templates / etc. vox oratio (alias vox speech) requires --features oratio (STT stack; separate from the mens command tree). Native train / serve / probe / merge-weights / merge-qlora / eval-local (Burn + Candle) require cargo build -p vox-cli --features gpu (alias mens-qlora). For Candle QLoRA on NVIDIA with linked CUDA kernels, use cargo vox-cuda-release (workspace alias → gpu,mens-candle-cuda; see .cargo/config.toml). Optional: vox-mens shim binary inserts the mens subcommand for argv ergonomics — use vox oratio for speech. cargo build -p vox-cli --features mens-base; add oratio on the same build for Oratio. See vox-cli build feature inventory. vox mens pipeline runs the dogfood corpus → eval → optional native train stages (replaces heavy orchestration in scripts/run_mens_pipeline.ps1). vox mens serve (HTTP/OpenAI-compatible API) requires gpu (Axum/control-plane pieces may additionally need execution-api for other REST surfaces — see crates/vox-cli/Cargo.toml). serve loads Burn LoRA *.bin or merged model_merged.bin (merge-weights); it does not load Candle merge-qlora f32 safetensor outputs. Corpus lives under vox mens corpus (e.g. extract, validate, pairs, mix, eval).

• vox mens train — native Mens training (contract/planner inside vox-populi (mens::tensor); use vox-mens argv shim when you want the binary that inserts mens). --backend lora (default): Burn + wgpu LoRA; --tokenizer vox (default) or --tokenizer hf with GPT-2-shaped HF config.json + optional HF embed warm-start from safetensors. --backend qlora: Candle + qlora-rs — NF4 frozen base linear(s) + trainable LoRA; mmap f32 for context embeddings (wte / model.embed_tokens). When all per-layer output-projection weights exist in shards, trains a sequential stack + LM head; else LM-head-only. --qlora-no-double-quant turns off qlora-rs double quant of scales (default: on). --qlora-require-full-proxy-stack fails preflight if expected middle projection keys are missing from shards (strict prod gate). --qlora-lm-head-only skips the middle o_proj stack even when shards are complete (stable CE on some CUDA dogfood paths; conflicts with --qlora-require-full-proxy-stack). --qlora-proxy-max-layers N caps stacked middle projections for ablation (0 = LM-head-only; conflicts with --qlora-lm-head-only when N > 0). --qlora-ce-last-k K (default 1) applies next-token CE on the last K positions per JSONL row (bounded by seq_len and 64). In-tree qlora-rs training_step_lm: pre-norm residual middles with 1/√depth per block and again before the LM head. --qlora-max-skip-rate <0..=1> aborts training when skipped JSONL rows exceed the fraction per epoch. --log-dir DIR re-spawns training in the background with a timestamped log (parent returns immediately — avoids IDE/agent wall-clock timeouts; tail the log). --background lowers process priority and caps VRAM fraction for long runs. Same --device story; CUDA / Metal with mens-candle-cuda / mens-candle-metal. QLoRA needs --tokenizer hf, --model, HF safetensors + tokenizer.json. --deployment-target mobile_edge or --preset mobile_edge: planner gates for edge export + --device cpu required. See reference/mens-training.md, reference/mobile-edge-ai.md, hf-finetune-capability-matrix.md. Python QLoRA: vox train / train_qlora.vox with --features mens-dei.

• vox mens merge-weights — merges a Burn LoRA checkpoint (*.bin) into model_merged.bin (gpu only). Does not apply Candle qlora adapter tensors.

• vox mens merge-qlora (alias merge-adapter) — merges candle_qlora_adapter.safetensors + sidecar meta (v2 candle_qlora_adapter_meta.json or v3 populi_adapter_manifest_v3.json) into f32 base shards (subset); *.bin Burn checkpoints are rejected (use merge-weights). See SSOT merge table.

• vox oratio (alias vox speech) — transcribe via vox-oratio (Candle Whisper, Rust + HF weights; not whisper.cpp). Build CLI with --features oratio. Includes transcribe, status, and sessionized listen (Enter-or-timeout gate, correction profile, route mode). Optional record-transcribe (default microphone → WAV → STT) needs --features oratio-mic. Env: VOX_ORATIO_MODEL, VOX_ORATIO_REVISION, VOX_ORATIO_LANGUAGE, etc. HTTP ingress: cargo run -p vox-audio-ingress (GET /api/audio/status, POST /api/audio/transcribe JSON {"path":"…"}, POST /api/audio/transcribe/upload multipart); relative paths use VOX_ORATIO_WORKSPACE or CWD. Bind with VOX_DASH_HOST / VOX_DASH_PORT (default 127.0.0.1:3847). See speech-capture-architecture.md. VS Code / Cursor Oratio flows: vox-vscode/README.md (MCP via vox mcp).

• Vox source (Speech.transcribe) — builtin module Speech: Speech.transcribe(path: str) → Result[str] uses Oratio and returns refined text (display_text()). Generated Rust crates depend on vox-oratio via codegen Cargo.toml.

• Corpus mix asr_refine — in mix YAML, set record_format: asr_refine on a source whose JSONL lines match mens/schemas/asr_refine_pairs.schema.json (noisy_text / corrected_text); output lines are prompt/response JSON for train.jsonl.

• Corpus mix tool_trace — set record_format { tool_trace for JSONL lines shaped like ToolTraceRecord in vox-corpus (task_prompt, tool_name, arguments_json, result_json, success, optional followup_text); schema mens/schemas/tool_trace_record.schema.json, example lines mens/data/tool_traces.example.jsonl. Emitted rows use category: tool_trace for --context-filter tool_trace during training.

• --features mens-dei: enables vox train (local provider bails with the canonical vox mens train --backend qlora … command; Together API; --native Burn scratch) and vox mens surfaces that call vox-orchestrator-d (generate, review, workflow, check, fix). RPC method names are centralized in crates/vox-cli/src/dei_daemon.rs (crate::dei_daemon::method::*) so CLI and daemon stay aligned. vox mens review uses ai.review; it does not embed the old TOESTUB/Fabrica/CodeRabbit tree.

• --features dei: vox dei (alias vox orchestrator) — DEI orchestrator CLI (commands::dei); build with cargo build -p vox-cli --features dei. Subcommands include status, submit <description> [--files …] [--priority urgent|background] [--session-id <id>] (session groups context like MCP session_id), assistant: multi-line stdin submit loop with --session-id (default cli-assistant) and optional --files / --priority, queue, rebalance, config, pause/resume, save/load, undo/redo. Workspace/snapshot/oplog (JSON on stdout, same payloads as MCP vox_workspace_*, vox_snapshot_*, vox_oplog): vox dei workspace create <agent_id>, vox dei workspace status <agent_id>, vox dei workspace merge <agent_id>, vox dei snapshot list [--agent-id <id>] [--limit <n>], vox dei snapshot diff <before> <after>, vox dei snapshot restore <snapshot_id> (S- prefix optional), vox dei oplog list [--agent-id <id>] [--limit <n>], vox dei takeover-status [--agent-id <id>] [--human] (repo + workspace + short snapshot/oplog tails; --human prints a short summary before the JSON).

• --features coderabbit: enables vox review coderabbit — GitHub/CodeRabbit batch flows in Rust (crates/vox-cli/src/commands/review/coderabbit/). Build: cargo build -p vox-cli --features coderabbit (often pair with mens-base if you omit default features: --no-default-features --features coderabbit,mens-base). Set GITHUB_TOKEN or GH_TOKEN.

vox review coderabbit (feature coderabbit)

Splits local changes into concern-based PRs with a real baseline (origin/<default> → cr-baseline-*) and git worktrees under .coderabbit/worktrees/ so the main working tree is not checked out per chunk. Plan-only (default): writes .coderabbit-semantic-manifest.json. Execute: add --execute (pushes baseline, opens PRs into baseline, writes .coderabbit/run-state.json for resume). Before opening worktree PRs, semantic-submit --execute re-scans the dirty tree and aborts with [drift] if the changed-file set no longer matches the plan (replan without --resume). The drift check ignores paths the command itself creates as untracked files (.coderabbit-semantic-manifest.json, .coderabbit/run-state.json) so they do not false-trigger drift.

For full-repo waves (--full-repo), the semantic manifest persists coverage counters (candidate_files, included_files, ignored_files) and plan output now prints ignored-rule buckets so operators can audit what was intentionally excluded from a “0-100%” run. semantic-submit can write a machine-readable ignore audit via --write-ignored-paths <file.json> and add one-off prefix exclusions with repeatable --extra-exclude-prefix (merged after Vox.toml). When any paths map to the unassigned bucket, plan output also prints top unassigned path prefixes; optional max_unassigned_ratio in Vox.toml fails planning if that fraction of included files is unassigned.

Manifest files (when written)

Vox.toml — optional [review.coderabbit]: tier, delay_between_prs_secs, max_files_per_pr, exclude_prefixes (path prefixes, forward slashes) -> drop noise paths from semantic/batch/stack planning; allow_markdown_prefixes — paths starting with these prefixes keep *.md / *.txt in semantic payloads (otherwise extension rules drop them for code-first review). Semantic grouping defaults to the bundled v1 rules in contracts/review/coderabbit-semantic-groups.v1.yaml. groups_config (repo-relative path) replaces that bundled file. semantic_workspace_crates (default true) runs cargo metadata once per plan and injects one prefix rule per workspace member under crates/<dir>/ (chunk names like crate_<package>). legacy_chunk_split (default false) uses legacy alphabetical splits for oversized groups; CLI mirror: semantic-submit --legacy-chunk-split. max_unassigned_ratio (optional, 0.0–1.0) aborts semantic-submit planning when the share of included files in the unassigned group exceeds the threshold.

Coverage SSOT: architecture/coderabbit-review-coverage-ssot.md defines the canonical scope and operational meaning of full-repository CodeRabbit coverage in Vox.

VoxDB-first ingest: vox review coderabbit ingest writes to external_review_* tables by default. Local .coderabbit/ingested_findings.json is now optional mirror state (--db-and-cache) rather than the authoritative source.

Git hygiene: .gitignore includes .coderabbit/worktrees/. You may commit .coderabbit/run-state.json if you want a shared run map (or keep it local). Ignored in drift/planning (normalized repo-relative paths, including leading ./): anything under .coderabbit/ (local tooling, worktrees). Chunk worktree overlays do not recurse into .coderabbit/ when copying from the main tree, so nested tool dirs are not duplicated.

• --features dashboard: reserved no-op in vox-cli. The old vox mens chat / agent / dei / learn commands are removed from the CLI surface (they depended on the historical vox-orchestrator module tree, not the minimal workspace crate). Use vox-codex-dashboard / the VS Code extension for dashboard-style surfaces.
• VOX_BENCHMARK=1: after training paths that invoke it, runs vox mens eval-local (requires gpu) using VOX_BENCHMARK_MODEL / VOX_BENCHMARK_DIR when set.

Related docs

• Rustdoc / layout: docs/src/reference/cli.md
• Ecosystem narrative (may include commands beyond this binary): how-to-cli-ecosystem.md
• Compiler pipeline (HIR path): reference/compiler-internals.md

title: "Crate: vox-cli" description: "Official documentation for Crate: vox-cli for the Vox language. Detailed technical reference, architecture guides, and implementation p" category: "reference" last_updated: 2026-03-24 training_eligible: true

Crate: vox-cli

Rust package path: crates/vox-cli. Produces the vox binary (src/main.rs) and vox-compilerd (src/bin/vox-compilerd.rs, stdio JSON dispatcher for dev and compiler-subcommand RPC).

Scope

This checkout’s vox-cli is a minimal compiler driver: clap dispatch, codegen orchestration, and a growing set of subcommands (including vox init). Feature-gated surfaces (Mens, review, MCP server, etc.) still depend on Cargo features — see reference/cli.md.

Authoritative user-facing command list: reference/cli.md.

Subcommands → source

Library / dispatch modules (not always exposed as vox subcommands): src/commands/info.rs (registry metadata), src/commands/runtime/** (extended run/dev/info/tree/shell). Inline script execution (runtime/run/{script,backend,sandbox}) builds with --features script-execution; Axum Mens inference server (commands/ai/serve) builds with --features execution-api (implies script-execution + gpu + Axum + vox-corpus validation helpers).

Shared modules

Library target

src/lib.rs owns the Cli parser, run_vox_cli(), and shared modules; src/main.rs only initializes tracing and calls run_vox_cli().

Build

cargo build -p vox-cli
# binaries: target/debug/vox(.exe), target/debug/vox-compilerd(.exe)

Install from the repo:

cargo install --locked --path crates/vox-cli

title: "CLI design rules" description: "Official documentation for CLI design rules for the Vox language. Detailed technical reference, architecture guides, and implementation p" category: "reference" last_updated: 2026-03-24 training_eligible: true

CLI design rules

Single source for shipped vox CLI conventions (see also reference/cli.md, cli-scope-policy.md, cli-reachability.md).

Hierarchy and naming

• One primary tree of nouns/verbs; avoid near-synonyms (update vs upgrade) for the same action.
• One canonical spelling per command in docs/registries/scripts; preserve compatibility aliases in clap (example: canonical mesh-gate, alias mens-gate).
• Latin-themed group commands (fabrica, mens, ars, recensio) mirror the flat top-level commands for discoverability; legacy top-level names remain active (not hidden).
• Subcommand depth should stay ≤ 2 for most flows; deeper trees only for dense domains (e.g. mens corpus).
• Retired / deprecated commands stay in the registry with status and doc’d migration (see command-surface-duals.md).

Help, output, and exit codes

• Every subcommand supports --help; root supports --version (via clap on VoxCliRoot).
• Machine-readable / JSON output belongs on stdout where a command documents it; diagnostics and errors on stderr.
• Prefer --json, --quiet, --verbose on subcommands that emit structured or noisy output; root sets hints via env (VOX_CLI_GLOBAL_JSON, VOX_CLI_QUIET) when using global flags.
• Non-zero exits must mean something actionable (document in help where non-obvious).

Description style standard

Use one canonical command description in clap for each command, then reuse it in docs/editor surfaces.

• What: one sentence describing the operation.
• Why/When: one short phrase for first-time guidance when non-obvious.
• Keep wording stable so vox commands output, docs tables, and editor quick-picks do not drift.

Global flags (root)

• --color auto|always|never — forwarded to vox_cli::diagnostics (NO_COLOR still wins when set).
• --json — sets VOX_CLI_GLOBAL_JSON=1 for subcommands that honor it.
• --verbose / -v — if RUST_LOG is unset, sets it to debug before tracing init.
• --quiet / -q — sets VOX_CLI_QUIET=1 for supported commands.
• doctor --json is the subcommand’s own machine JSON; vox --json doctor only sets VOX_CLI_GLOBAL_JSON for code paths that read it — do not assume they are interchangeable.

Completions

• vox completions <shell> — use clap_complete; shells: bash, zsh, fish, powershell, elvish. Install by redirecting stdout to the appropriate completion path for your shell (see reference/cli.md).

Adding or renaming commands

1. Implement in crates/vox-cli (and internal surfaces as needed).
2. Add or update the vox-cli projection in contracts/operations/catalog.v1.yaml (schema: contracts/operations/catalog.v1.schema.json), then run vox ci operations-sync --target cli --write (or --target all) so contracts/cli/command-registry.yaml stays generated.
3. Update docs/src/reference/cli.md and, for top-level reachability, cli-reachability.md when reachability_required is not false.
4. Run vox ci operations-verify and vox ci command-compliance before merge (also enforced in CI).

title: "CLI command reachability" description: "Official documentation for CLI command reachability for the Vox language. Detailed technical reference, architecture guides, and implemen" category: "reference" last_updated: 2026-03-24 training_eligible: true

CLI command reachability

This page maps vox subcommands in crates/vox-cli/src/lib.rs -> their implementation modules under crates/vox-cli/src/commands/.

Reachable from default / feature matrix

vox-compilerd RPC (not CLI variants)

Daemon dispatch lives in crates/vox-cli/src/compilerd.rs. Methods call commands::build, check, bundle, fmt, doc, test, run, dev — not the removed commands/compiler/ tree.

vox-orchestrator-d (orchestrator daemon sidecar)

vox-orchestrator-d is built from the orchestrator crate (not vox-cli) and exposes JSON-line orch.* methods for MCP sidecar pilots. Optional ADR 022 sidecar: vox-orchestrator-d can run as a long-lived process (VOX_ORCHESTRATOR_DAEMON_SOCKET TCP/stdio). MCP currently uses a split-plane transition model: daemon-aligned RPC pilots may own task/agent lifecycle slices, but many VCS/context/event/session features still read embedded stores unless explicitly moved behind daemon contracts.

• Build: cargo build -p vox-orchestrator --bin vox-orchestrator-d
• Run (TCP): VOX_ORCHESTRATOR_DAEMON_SOCKET=127.0.0.1:9745 target/debug/vox-orchestrator-d
• Run (stdio): VOX_ORCHESTRATOR_DAEMON_SOCKET=stdio target/debug/vox-orchestrator-d

When using with MCP, set MCP-side VOX_ORCHESTRATOR_DAEMON_SOCKET to the same TCP peer and optionally enable pilots with VOX_MCP_ORCHESTRATOR_RPC_READS=1 / VOX_MCP_ORCHESTRATOR_RPC_WRITES=1. Repo-id mismatch warning/error behavior is controlled by VOX_MCP_ORCHESTRATOR_DAEMON_REPOSITORY_ID_STRICT.

Removed / non-compiled trees (historical)

The following directories under commands/ were not referenced from commands/mod.rs or the CLI and have been removed to reduce dead surface {

• commands/compiler/ — duplicate of canonical build / check / doc / fmt / bundle paths used by compilerd and CLI.
• commands/pkg/ — unwired package manager experiment.
• commands/serve_dashboard/ — superseded by vox-codex-dashboard / extension flows.
• commands/infra/ — legacy unwired tree; vox deploy is implemented in commands::deploy (delegates to vox-container).
• commands/learn.rs, commands/dashboard.rs — orphan modules with no mod declaration.

Shared subtrees

• commands::runtime — used by run (script lane), dev re-exports, and feature-gated script execution.
• commands::extras — snippet, share, skill, ludus, ARS helpers.