dominus-platform-cli

Agent-native CLI for the Dominus platform with a 273-tool dominus-mcp catalog. All 273 catalog tools have routing entries and are invokable today. 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            # one of the 273 currently routed tools

Installed globally (npm i -g dominus-platform-cli) the binary is dominus. This checkout targets 0.2.33. Its validators keep the source/snapshot wire schemas at v1 while validating the declared contract set as data: contract ids must be unique and non-empty, and registry_version is the schema generation (a positive integer), not a content-revision selector. The vendored version 3/14 catalog adds the strict database-placement lifecycle contract and retains 18 managed debts: D11, D14, and D16 are closed; D14's hand-rolled and source-copy transport inventories are both zero; and D12 Sync-to-Admin topology plus D17 Publisher control-read are accepted-by-design. Install or refresh the matching release with npm i -g [email protected].

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 273 catalog tools grouped by family (offline, from the shipped catalog) | | dominus whoami | Validate DOMINUS_USER_TOKEN and print your identity (user_id, email, display_name) | | dominus <tool> [--flags] | Invoke a routed catalog 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) | | dominus contracts conform [options] | Coverage + convergence report (report-only; always exits 0) |

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

Identity check

Verify a user credential before anything else — this is the command the public getting-started doc tells a new user to run first:

npm i -g dominus-platform-cli          # installs the `dominus` binary
export DOMINUS_USER_TOKEN=<your token> # operator/user token, not a project PSK
dominus whoami                         # prints your identity or a clear error

Success prints one JSON document on stdout (exit 0):

{ "user_id": "usr_...", "email": "[email protected]", "display_name": "Ada" }

An invalid token fails non-zero with an actionable message on stderr — no stack trace, no raw 401 body, and the token itself is never echoed. whoami talks to the published MCP endpoint https://mcp.getdominus.app; set DOMINUS_MCP_URL to override it (e.g. for a staging or development deployment).

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 (30s abort; 3 attempts with backoff on timeout/5xx), 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. If pending_local_projection is present, the named tool metadata is a coordinated local projection awaiting MCP deployment and live parity. The next successful npm run refresh-catalog rewrites the catalog and removes that marker.
• catalog/routing.json — per-tool routing overlay (npm run merge-routing): 203 tools call dominus-sdk-nodejs methods, 42 hit raw gateway routes (WAF-safe base64 envelope), and 28 are hand-written composites (273 routed tools total). authority_run_kinds uses the raw gateway route /svc/authority/run-kinds until the released Node SDK exposes authority.runKinds; authority_company_slug_inventory and authority_provisioning_history_migrate follow the same raw-gateway pattern. ref_resolve is adapter-declared on the SDK lane (refs.resolve).
• Parity gate (npm run parity-check) — CI diffs the catalog against the live tools/list (names + schemas) and fails the publish on drift. It also runs the F-3 projection cross-check, which validates that a gateway_path's service segment is registered in the endpoint catalog; that check skips (rather than reporting drift) when the endpoint catalog is unreadable or has no services registry, which is the normal CI shape. Mode semantics (v1-warn / v2-fail) are canonical in docs/deprecation-policy.md.
• 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/agent-guide/INDEX.md — read-first agent pack (current snapshot docs/agent-guide/2026-10-26-1300-cli-0.2.33/00-reading-order.md)
• Knowledge graph: graphify-out/GRAPH_REPORT.md — query with graphify-run query "<question>" before grepping.
• docs/atlas/INDEX.md — truth map, stale surfaces, proof ladder (2026-08-04)
• docs/janitor/2026-10-26-1300-dominus-cli-cleanup-audit.md — latest cleanup audit
• docs/usage-reference.md — per-tool reference for the 273-tool catalog. Still not safely regenerable as-is — scripts/generate-usage.mjs would drop the file's hand-maintained preamble, so edit it surgically. See docs/agent-guide/2026-10-14-1300-cli-0.2.33/09-known-risks-and-debt.md.
• The current snapshot also documents two things that are easy to get wrong: catalog/routing.json is built from adapter-declared sdk entries plus the five catalog/routing/*.json overlays (203 + 70, not "273 from five files"), and onboarding_invite_user sends an empty mint body — the portal binds the operator server-side. See 02-repo-map-and-entrypoints.md and 08-security-privacy-and-secrets.md.

Two contracts changed on 2026-09-12 and are easy to get wrong:

• Exit path. src/cli.ts no longer forces a top-level process.exit; success goes through finishCli and failure through failCli, and src/output.ts waits for the final stdout flush. Reintroducing a forced exit reintroduces the Windows/Node 24 libuv abort. Guarded by tests/output.test.ts.
• Parity gate. All three publish workflows now pass --mode=v2-fail, so drift blocks a publish. Bare npm run parity-check is still v1-warn locally.

One more is easy to get wrong as of 0.2.32: CLI-only input flags live in scripts/local-schema-additions.mjs, not in catalog/tools.json. That module is re-applied by refresh-catalog and subtracted by parity-check; a flag added anywhere else is erased by the next refresh. The current entries are logs_query, redis_keys, storage_get_url, and storage_list. artifact_list_v2 was retired from that module by 1e4a328 once the live MCP began publishing include_versions/cursor itself — re-adding it is now the drift the --mode=v2-fail gate rejects.