CLI Reference

The CLI uses the same service layer as the local HTTP API. It is useful for tests, runbooks, migrations, and operator checks when the dashboard is not the right tool.

For headless agent use, start with agent-client-contract. It returns the same operation classification exposed by GET /agent-client/contract, including which commands are agent-readable, agent-steering, human-only, operator-only, or blocked.

Run commands with:

npm run cli -- <command> [args]

Run And Coordinator Commands

• create-run --input examples/coding-run-input.json
• create-run --goal "..." --verifier-command '["node","-e","process.exit(0)"]'
• create-coordinator-run --request "..."
• agent-client-contract
• get-run <run-id>
• list-runs
• pause-run <run-id>
• resume-run <run-id>
• cancel-run <run-id>
• run-worker-cycle [run-id]
• get-delegation-plan <run-id>
• list-task-sessions <run-id>
• get-task-session <task-session-id>
• add-task-guidance <task-session-id> --instruction "..."
• coordinator-report <run-id>
• command-center
• run-workspace <run-id>

Approval, Artifact, And Audit Commands

• approval-queue
• approve-checkpoint <approval-id> [--reviewer-note "..."]
• reject-checkpoint <approval-id> [--reviewer-note "..."]
• artifact-index <run-id>
• list-artifacts <run-id>
• get-timeline <run-id>
• audit-view <run-id>
• replay-packet <run-id> [output-json-path]
• replay-from-packet <replay-packet-json-path> --dry-run
• export-audit <run-id> [output-json-path]

Secrets And Migration Commands

• set-secret --name "OpenAI" --kind provider-api-key --provider openai --value-file ./secret.txt [--env-var OPENAI_API_KEY]
• list-secrets [--kind provider-api-key] [--provider openai] [--status present]
• get-secret <secret-id>
• check-secret <secret-id>
• check-secrets [--status present]
• delete-secret <secret-id>
• backup-manifest [output-json-path]
• verify-restore [data-dir] [--manifest backup-manifest.json]

Secret values are write-only. CLI output returns metadata, hashes, redacted previews, and material status only. Use --env-var when a provider adapter needs a specific environment variable name injected during execution.

Approval decisions made through the CLI are recorded as human-owned decisions. Approval records include whether evidence, hashes, and policy class were reviewed so headless agents can inspect approval state without being able to approve high-risk work themselves.

Automation Commands

• create-automation --name "..." --request "..." [--workflow-template-id provider-smoke]
• create-automation --input automation.json
• list-automations [--status enabled]
• get-automation <automation-id>
• enable-automation <automation-id>
• disable-automation <automation-id>
• pause-automation <automation-id>
• preview-automation <automation-id>
• trigger-automation <automation-id>

V1 supports manual triggering. Schedule, file-watch, and webhook trigger metadata can be represented, but a trigger worker is a later implementation slice.

Memory And Conversation Commands

• conversation-summary <conversation-id>
• list-memory-candidates [--status candidate] [--conversation-id <conversation-id>]
• promote-memory-candidate <memory-candidate-id>
• reject-memory-candidate <memory-candidate-id>
• memory-context-preview [--conversation-id <conversation-id>] [--run-id <run-id>]
• create-memory-review [--conversation-id <conversation-id>] [--archive-stale]
• run-memory-maintenance [--conversation-id <conversation-id>] [--archive-stale] [--promote-high-confidence]
• list-memory-reviews
• get-memory-review <memory-review-id>
• transcribe-audio <audio-session-id> [--audio-path ./note.wav] [--transcript-file transcript.txt]

Routine maintenance can summarize stale conversations, extract memory candidates, run review checks, optionally archive stale records, and optionally promote high-confidence candidates.

transcribe-audio records a local STT/import request against an audio session. When transcript text is supplied, it appends an auditable input-transcript event; local Whisper command execution is a later adapter.

Model And Profile Commands

• model-catalog
• model-routing-preview [--role <role>] [--task-kind coding] [--privacy local-only]
• list-model-routing-policies [--status active]
• get-model-routing-policy <policy-id>
• upsert-model-routing-policy --preferred-provider <provider> --rationale "..." [--role <role>]
• list-tools
• list-skills
• list-agent-profiles
• get-agent-profile <agent-profile-id>
• create-agent-profile-change --input profile-change.json
• create-agent-profile-change --role <role> --label <label> --reason "..."
• list-agent-profile-changes [--status pending]
• get-agent-profile-change <change-id>
• approve-agent-profile-change <change-id> [--reviewer-note "..."]
• reject-agent-profile-change <change-id> [--reviewer-note "..."]

Profile changes are review-gated. Approval activates a user profile; rejection preserves the audit trail.

Server Command

• serve-api

The CLI command prints the dev-server hint. Start the always-on local API with:

npm run dev:api