dominus-platform-cli

Agent-native CLI for the Dominus platform with 100% dominus-mcp tool parity (261 tools). One-shot, stateless, JSON-first: built so an AI agent with a shell can operate the platform without an MCP client.

Quickstart (agents)

export DOMINUS_USER_TOKEN=<your user token>   # or DOMINUS_TOKEN=<project PSK>
export DOMINUS_PROJECT=<project-slug>         # ambient scope (or pass --project per call)
export DOMINUS_ENV=production                 # development | staging | production

npx dominus-platform-cli context              # one-call bootstrap: auth, scope, inventory
npx dominus-platform-cli db_tables            # any of the 261 tools

Installed globally (npm i -g dominus-platform-cli) the binary is dominus.

Output contract

• stdout: exactly one JSON document on success, exit 0.
• stderr: { "error": { "code", "message", "tip" } } on failure, exit non-zero. The tip tells the agent how to self-recover.
• --pretty opts into indented JSON. Never interactive, no ANSI, no prompts.

Commands

| Command | Purpose | | --- | --- | | dominus context | Bootstrap blob: auth status, resolved scope, tool count, next calls | | dominus capabilities | All 261 tools grouped by family (offline, from the shipped catalog) | | dominus <tool> [--flags] | Invoke a tool; flags are the tool's input-schema properties | | dominus <tool> --show-schema | Print a tool's input schema (offline); legacy --schema also works when the tool has no schema input | | dominus call <tool> --json '{...}' | Invoke with a JSON payload (also @file.json or - for stdin) | | dominus docs [topic] | Platform orientation docs (offline) | | dominus contracts check [options] | Plan or run kernel-contract proof obligations (offline; not an MCP tool) |

See docs/usage-reference.md for the generated per-tool reference and docs/contracts.md for contract-check subjects, statuses, and receipts.

Auth modes

| Mode | Env var | How it executes | | --- | --- | --- | | Service | DOMINUS_TOKEN (project PSK) | SDK mints service JWTs locally; token is project-bound | | User | DOMINUS_USER_TOKEN | Exchanged once per (project, env) for a selected-scope JWT via the MCP server's POST /auth/scope-token, cached in ~/.dominus/cache.json until expiry |

Scope is resolved from --project/--env flags or DOMINUS_PROJECT/DOMINUS_ENV env vars on every call — nothing is persisted, so parallel agents never collide. select_project validates access and emits an exportable env block instead of storing state.

Architecture

• catalog/tools.json — committed catalog refreshed from the live MCP server (npm run refresh-catalog); ships in the package so discovery works offline.
• catalog/routing.json — per-tool routing overlay (npm run merge-routing): 198 tools call dominus-sdk-nodejs methods, 37 hit raw gateway routes (WAF-safe base64 envelope), and 26 are hand-written composites.
• Parity gate (npm run parity-check) — CI diffs the catalog against the live tools/list (names + schemas) and fails the publish on drift.
• catalog/contracts.json is vendored, hash-bound output from Platform Worker's isolated contract compiler. npm run refresh-contracts promotes it only after structural compilation and workspace-reference verification both pass.
• DominusContracts.check() / dominus contracts check is the dedicated local contract interface. It plans from Git changes, deduplicates shared proofs, runs only installed adapters, and keeps static/local/integration/deploy/live evidence separate. It is deliberately absent from catalog/tools.json.

Publish lanes

Push to a lane branch to publish via GitHub Actions (version-exists skip):

| Branch | npm package | | --- | --- | | dominus-development | dominus-platform-cli-dev | | dominus-staging | dominus-platform-cli-staging | | dominus-production | dominus-platform-cli |

Secrets per GitHub environment: NPM_TOKEN (publish), DOMINUS_USER_TOKEN (parity gate).

Development

npm ci
npm run build     # tsc -> dist/
npm test          # vitest unit tests
npm run parity-check
npm run contracts-parity-check -- --vendored-only
# After Platform Worker registry changes pass both receipts:
npm run refresh-contracts -- --workspace C:/developer/codingroot/repos
node scripts/generate-usage.mjs

Agent Orientation

• docs/atlas/INDEX.md — truth map, stale surfaces, proof ladder (2026-07-03)
• docs/usage-reference.md — generated per-tool reference