Skip to main content

Source: docs/manual/cli.md

This page is generated by site/scripts/sync-manual-docs.mjs.

CLI Reference

This is a developer-level flag reference for each command under cmd/*. For the full list of commands grouped by function, see cmd/README.md. This page covers all current cmd/* entrypoints (63 commands as of 2026-02-23).

Common Workflows​

Run an Agent and Inspect Results​

Seed the tool registry, execute an agent run, inspect the result, then replay from a specific step:

# 1. Seed the tool registry (first time or after tool changes)
go run ./cmd/seed-registry --id default --version v2.0.0

# 2. Execute an agent run
go run ./cmd/run --prompt "Fetch https://example.com and return the status code" --max-steps 6

# 3. Query the run state (use the workflow-id from step 2 output)
go run ./cmd/query --workflow-id <workflow-id> --query current_state

# 4. View the decision log
go run ./cmd/query --workflow-id <workflow-id> --query decision_log

# 5. Replay from step 2 with a different registry version
go run ./cmd/replay --workflow-id <workflow-id> --from-step 2 --registry-version v2.1.0

Supervisor Workflow​

Create a multi-agent supervisor run, monitor progress, and approve delegated tasks:

# 1. Run a broadcast supervisor (sends prompt to all agents)
go run ./cmd/supervisor-run --pattern broadcast --prompt "Summarize current system status"

# 2. Query supervisor state
go run ./cmd/supervisor-query --workflow-id <workflow-id>

# 3. Check for pending approvals
go run ./cmd/query --workflow-id <workflow-id> --query pending_approvals

# 4. Approve a pending request
go run ./cmd/approve --workflow-id <workflow-id> --request-id <request-id> --approve=true --reason "Looks good"

Debug a Failed Run​

Investigate why an agent run failed:

# 1. List recent runs (look for failed ones)
go run ./cmd/query --workflow-id <workflow-id> --query current_state

# 2. View the full decision log to find where it went wrong
go run ./cmd/query --workflow-id <workflow-id> --query decision_log

# 3. Inspect the causal trace for the last step
go run ./cmd/query --workflow-id <workflow-id> --query causal_trace --latest

# 4. Compare with a replay to see if the failure is reproducible
go run ./cmd/replay-compare --workflow-id <workflow-id> --prompt "original prompt"

Tool Management​

Seed the registry, list tools, and provide quality feedback:

# 1. Seed registry with built-in and MCP tools
go run ./cmd/seed-registry --id default --version v2.0.0

# 2. List all registered tools
go run ./cmd/list-tools --registry-id default --registry-version v2.0.0

# 3. Register a composite tool
go run ./cmd/compose-tool --name enrich_ticket --steps ./composite_steps.json --registry-version v2.1.0

# 4. Submit tool quality feedback
go run ./cmd/tool-feedback --tool http_get --rating 5 --comment "Fast and reliable"

Memory Operations​

Query and inspect agent memory across runs:

# 1. Query episodic memory for a specific run
go run ./cmd/memory-query --type episodic --run-id <run-id> --limit 10

# 2. Search semantic memory
go run ./cmd/memory-query --type semantic --namespace default --query "deployment status" --k 5

# 3. Look up procedural memory by name
go run ./cmd/memory-query --type procedural --name "incident-triage"

cmd/agent-version​

  • --action (default list) list|get|set
  • --version version string
  • --changelog changelog text
  • --compatible comma-separated compatible versions

cmd/agent-capability​

  • --action register|list|scores (required)
  • --agent agent name (register requires it; optional for list/scores)
  • --capability capability name (register requires it)
  • --description capability description (register)
  • --test-coverage capability has explicit test coverage (register, default false)
  • --tenant tenant id (default default) Examples:
  • go run ./cmd/agent-capability --action register --agent planner --capability triage --description \"Triage incidents\" --test-coverage
  • go run ./cmd/agent-capability --action scores --tenant default

cmd/provenance-query​

  • --run-id run id to query (required)
  • --step optional step index filter (default -1, all steps)
  • --node-id optional node id for ancestor/descendant traversal
  • --diff-run-id optional second run id for diff mode
  • --depth traversal depth for ancestor/descendant mode (default 5)
  • --format output format text|json (default text)
  • --tenant tenant id (default default) Examples:
  • go run ./cmd/provenance-query --run-id run-123 --step 2
  • go run ./cmd/provenance-query --run-id run-a --diff-run-id run-b --format json

cmd/answer​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)
  • --request-id question request id (required)
  • --answer answer text

cmd/approve​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)
  • --request-id approval request id (required)
  • --approve approve or reject (default true)
  • --reason reason text
  • --hint optional operator hint injected into the next step after metacognitive escalation approval

cmd/audit-export​

  • --format soc2|hipaa|json|csv (default from CRUVERO_AUDIT_EXPORT_FORMAT)
  • --tenant tenant id (default default)
  • --from start timestamp in RFC3339
  • --to end timestamp in RFC3339
  • --out output file path (stdout if empty)
  • --include-pii include unredacted details when available (default false)
  • --limit max events to export (default 5000)

cmd/backup​

Subcommands:

  • dump
    • --out output path
    • --s3-key upload key
    • --format custom|plain|tar|directory (default from CRUVERO_BACKUP_PG_DUMP_FORMAT)
    • --timeout command timeout (default 20m)
  • restore
    • --in local dump path
    • --s3-key download key
    • --clean drop/recreate objects before restore (default true)
    • --timeout command timeout (default 30m)
  • registry-export
    • --tenant optional tenant filter
    • --out output JSON path
    • --s3-key upload key
    • --timeout query timeout (default 30s)
  • registry-import
    • --tenant optional tenant filter
    • --in input JSON path
    • --s3-key download key
    • --timeout import timeout (default 60s)
  • audit-archive
    • --days archive cutoff in days (default from CRUVERO_BACKUP_AUDIT_ARCHIVE_DAYS)
    • --tenant optional tenant filter
    • --out local archive path
    • --s3-key upload key
    • --dry-run skip deletion (default false)
    • --delete delete after successful upload (default true)
    • --timeout operation timeout (default 5m)

cmd/control​

  • --workflow-id workflow id (required)
  • --action pause|resume|step (default pause)

cmd/cost-query​

  • --workflow-id workflow id (required)

cmd/compose-tool​

  • --name composite tool name (required)
  • --description composite tool description
  • --steps path to JSON array of composite steps (required)
    • each step supports tool_name, arg_mapping, output_key, optional max_attempts, optional timeout_ms
  • --input-schema path to composite input JSON schema
  • --registry-id registry id (default default)
  • --registry-version registry version to write (required)
  • --dry-run validate only, do not register
  • --tenant tenant id (default default) Examples:
  • go run ./cmd/compose-tool --name enrich_ticket --steps ./composite_steps.json --registry-version v2.1.0 --dry-run
  • go run ./cmd/compose-tool --name enrich_ticket --steps ./composite_steps.json --registry-version v2.1.0

cmd/diff-test​

  • --prompt prompt (default Summarize the latest status)
  • --model-a model A id
  • --model-b model B id
  • --registry-id tool registry id (default default)
  • --registry-version tool registry version (default latest)

cmd/docs-linkcheck​

  • --root docs directory tree to scan for Markdown links (default docs) Examples:
  • go run ./cmd/docs-linkcheck --root docs

cmd/edit-state​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)
  • --file path to state JSON (required)

cmd/graph-approve​

  • --workflow-id workflow id (required)
  • --request-id request id (required)
  • --approve approve or reject (default true)

cmd/graph-edit-state​

  • --workflow-id workflow id (required)
  • --file state JSON file (required)

cmd/graph-query​

  • --workflow-id workflow id (required)

cmd/graph-run​

  • --workflow-id workflow id (optional)

cmd/graph-run-llm​

  • --workflow-id workflow id (optional)

cmd/graph-worker​

  • No flags

cmd/inspect​

  • --workflow-id workflow id (required)

cmd/list-tools​

  • --registry-id tool registry id (default default)
  • --registry-version tool registry version (default v2.0.0)

cmd/memory-query​

  • --type episodic|semantic|procedural (default episodic)
  • --run-id run id for episodic
  • --namespace namespace for semantic
  • --name name for procedural
  • --query semantic query text
  • --k semantic top-k (default 5)
  • --limit episodic limit (default 10)
  • --types episodic types (comma-separated)

cmd/vaccinate​

  • --signature-hash anomaly signature hash to vaccinate
  • --procedure fix procedure text
  • --resolved-by resolver identity (default cli)
  • --list list unresolved anomalies
  • --quarantine list active quarantined tools
  • --release release quarantined tool name
  • --reason quarantine release reason (default manual release via vaccinate cli)
  • --tenant tenant id (default default) Examples:
  • go run ./cmd/vaccinate --list
  • go run ./cmd/vaccinate --signature-hash abc123 --procedure \"Validate URL and retry\" --resolved-by oncall
  • go run ./cmd/vaccinate --release http_get --reason \"validated fix in staging\"

cmd/migrate​

  • --dir migrations directory (default migrations)
  • --cmd up|down|steps (default up)
  • --steps steps for steps command

cmd/model-prefs​

  • --action get|set (default get)
  • --namespace model preference namespace (default default)
  • --models comma-separated model ids

cmd/models-list​

  • --id model id

cmd/models-refresh​

  • --source model source openrouter|azure|openai|google (default openrouter)

cmd/playground​

  • --mode dry_run|scenario|chaos (required)
  • --prompt prompt text (required)
  • --scenario scenario JSON path (required for scenario mode)
  • --scenario-strict-args fail scenario step when expected args mismatch (default false)
  • --chaos-failure-rate chaos failure rate (default 0.2)
  • --chaos-timeout-rate chaos timeout rate (default 0.1)
  • --chaos-timeout injected timeout sleep duration before returning deadline exceeded (default 30s)
  • --chaos-contradiction-rate chaos contradiction rate (default 0.05)
  • --chaos-max-failures max injected failures/timeouts (default 5)
  • --registry-id tool registry id (default default)
  • --registry-version tool registry version (default latest)
  • --max-steps max workflow steps for scripted run (default 6)
  • --model optional model label stored in run config metadata
  • --format output format text|json (default text)
  • --out optional output file path for report artifacts Examples:
  • go run ./cmd/playground --mode dry_run --prompt \"summarize status\" --format json --out reports/playground-dry-run.json
  • go run ./cmd/playground --mode scenario --prompt \"simulate sequence\" --scenario docs/examples/playground_scenario_basic.json --scenario-strict-args
  • go run ./cmd/playground --mode chaos --prompt \"chaos check\" --chaos-failure-rate 0.5 --chaos-timeout 5s --chaos-max-failures 2

Example scenario files:

  • docs/examples/playground_scenario_basic.json
  • docs/examples/playground_scenario_strict_args.json

cmd/python-manifest​

  • --python python executable path (default python3)

cmd/bash-allowlist​

  • --command optional command to validate
  • --allow-network include network allowlist (requires CRUVERO_BASH_ALLOW_NETWORK=true)

cmd/query​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)
  • --query current_state|pending_approvals|pending_questions|decision_log|causal_trace (default current_state)
  • --step step index for causal trace
  • --latest use latest step for causal trace (default false)

cmd/record-fixtures​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)
  • --out output file (optional)

cmd/replay​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)
  • --from-step start step index (default 0)
  • --state optional state JSON
  • --decision-overrides optional decision overrides JSON
  • --registry-version tool registry version (default latest)
  • --provider llm provider openrouter|azure|openai|google (default from CRUVERO_LLM_PROVIDER)
  • --repair enable tool repair loop (default true)
  • --repair-attempts tool repair max attempts (default 3)
  • --repair-timeout tool repair timeout (default 1m)
  • --tool-search filter tool list for decision context (default true)
  • --tool-limit max tools to include in decision context (default 20)
  • --provider llm provider openrouter|azure|openai|google (default from CRUVERO_LLM_PROVIDER)

cmd/replay-compare​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)
  • --prompt original prompt (required)
  • --registry-id tool registry id (default default)
  • --registry-version tool registry version (default latest)
  • --from-step step index to compare
  • --timeout replay timeout (default 10m)
  • --out output file for replay decision log (optional)

cmd/run​

  • --prompt initial prompt (default Find the status code of https://example.com)
  • --model override model id
  • --registry-id tool registry id (default default)
  • --registry-version tool registry version (default latest)
  • --max-steps max steps (default 6)
  • --approval-timeout approval timeout (default 10m)
  • --repair enable tool repair loop (default true)
  • --repair-attempts tool repair max attempts (default 3)
  • --repair-timeout tool repair timeout (default 1m)
  • --tool-search filter tool list for decision context (default true)
  • --tool-limit max tools to include in decision context (default 20)
  • --provider llm provider openrouter|azure|openai|google (default from CRUVERO_LLM_PROVIDER)
  • --spec-models comma-separated models for speculative execution
  • --spec-select lowest_cost|highest_similarity (default lowest_cost)
  • --soft-deadline soft deadline in RFC3339 format
  • --hard-deadline hard deadline in RFC3339 format
  • --fast-model model id to use under high/critical deadline pressure
  • --memory-ref repeatable, format type:runID:namespace:name

cmd/seed-registry​

  • --id registry id (default default)
  • --version registry version (default v2.0.0)
  • --tenant tenant id (default default)
  • --composites path to JSON array of composite tool definitions to include during seed

cmd/supervisor-query​

  • --workflow-id workflow id (required)
  • --full return full state (default false)

cmd/supervisor-run​

  • --pattern delegate|broadcast|debate|pipeline|map_reduce|voting|saga (default delegate)
  • --prompt supervisor prompt (default Summarize the latest status)
  • --registry-id tool registry id (default default)
  • --registry-version tool registry version (default latest)
  • --repair enable tool repair loop (default true)
  • --repair-attempts tool repair max attempts (default 3)
  • --repair-timeout tool repair timeout (default 1m)
  • --tool-search filter tool list for decision context (default true)
  • --tool-limit max tools to include in decision context (default 20)
  • --agents JSON file of agent specs
  • --items JSON file of map-reduce items
  • --saga JSON file of saga steps

cmd/supervisor-signal​

  • --workflow-id workflow id (required)
  • --kind message|event (default message)
  • --to message recipient (default supervisor)
  • --from message sender (default cli)
  • --topic event topic (default info)
  • --payload payload content

cmd/temporal-agent​

This CLI auto-loads .env if present in the current directory.

temporal-agent init​

  • --name agent name (default my-agent)
  • --module go module name
  • --force overwrite existing files

temporal-agent dev​

  • --registry-version tool registry version to seed (default v2.0.7)
  • --cruvero-path path to cruvero repo (defaults to repo root)
  • --seed seed tool registry before starting worker (default true)
  • --config path to env file to load
  • --no-worker skip starting worker

temporal-agent latest-run​

  • --status filter by Running|Completed|Failed

temporal-agent inspect​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)

temporal-agent cost​

  • --workflow-id workflow id (required)
  • --run-id run id (optional)

temporal-agent status​

  • --config path to env file to load

temporal-agent run​

  • --prompt prompt to run (default Summarize the status)
  • --cruvero-path path to cruvero repo (defaults to repo root)
  • --config path to env file to load

cmd/trace-query​

  • --run-id run id (required)
  • --step step index (default -1)
  • --tool tool name
  • --latest latest trace for run (default false)

cmd/worker​

  • No flags

cmd/ui​

  • --addr listen address (default :8080)
  • --auth none|keycloak (default from CRUVERO_UI_AUTH)
  • --jwks-url Keycloak JWKS URL (default from CRUVERO_UI_JWKS_URL)
  • --issuer JWT issuer (default from CRUVERO_UI_ISSUER)
  • --audience JWT audience (default from CRUVERO_UI_AUDIENCE)
  • --readonly disable approve/replay (default from CRUVERO_UI_READONLY)
  • --cors enable CORS for API endpoints (default from CRUVERO_UI_CORS)
  • --admin-token admin token for quota mutation endpoints (default from CRUVERO_UI_ADMIN_TOKEN)

cmd/api​

  • --port, -p API listen port (default 8900) Examples:
  • go run ./cmd/api --port 8900

cmd/api-verify​

  • --base-url API base URL (required, for example http://localhost:8900)
  • --api-key value for X-API-Key
  • --token bearer token for Authorization
  • --tenant-id value for X-Cruvero-Tenant-Id
  • --timeout per-request timeout (default 10s)
  • --output, -o output path (default stdout)
  • --spec path to OpenAPI spec file (default auto-generated)
  • --full include write/destructive endpoints Examples:
  • go run ./cmd/api-verify --base-url http://localhost:8900
  • go run ./cmd/api-verify --base-url http://localhost:8900 --full --output reports/api-verify.json

cmd/embed-worker​

embed-worker is a long-running service process and is configured by environment variables (no CLI flags). Required/runtime-critical env:

  • CRUVERO_EVENTS_BACKEND=nats
  • CRUVERO_POSTGRES_URL
  • embedding config (CRUVERO_EMBEDDING_PROVIDER, CRUVERO_EMBEDDING_MODEL, provider API key) Examples:
  • CRUVERO_EVENTS_BACKEND=nats go run ./cmd/embed-worker

cmd/event-bench​

  • --nats-url NATS server URL (default nats://localhost:4222)
  • --ui-url UI base URL (default http://localhost:8080)
  • --prefix events subject prefix (default cruvero)
  • --workflow-id workflow id tag for benchmark events
  • --warmup-events, --warmup-rate
  • --steady-events, --steady-rate
  • --stress-events, --stress-rate
  • --pass-timeout max duration per pass (default 1m30s) Examples:
  • go run ./cmd/event-bench --nats-url nats://localhost:4222 --workflow-id bench-run-1

cmd/event-bus​

Global flags:

  • --nats-url NATS server URL (default CRUVERO_NATS_URL or nats://localhost:4222)
  • --format output format table|json (default table) Subcommands:
  • status
  • streams
  • consumers
  • subscribe <subject>
  • publish <subject> <json>
  • purge <stream> Examples:
  • go run ./cmd/event-bus --nats-url nats://localhost:4222 status
  • go run ./cmd/event-bus publish cruvero.events.run.started '{"run_id":"run-1"}'

cmd/event-replay​

  • --subject subject pattern to replay (required)
  • --nats-url NATS server URL (default nats://localhost:4222)
  • --stream optional stream name override
  • --since lookback duration (2h, 30m, 7d)
  • --start-time RFC3339 start time (mutually exclusive with --since)
  • --limit max events (0 = unlimited)
  • --format output format json|table (default json) Examples:
  • go run ./cmd/event-replay --subject cruvero.events.> --since 30m --format table

cmd/mcp-announce​

  • --server MCP server name (required)
  • --nats-url NATS server URL (default from config)
  • --transport MCP transport stdio|http|sse (default stdio)
  • --endpoint MCP endpoint URL (required for http|sse)
  • --heartbeat heartbeat interval (default 30s)
  • --prefix NATS subject prefix (default cruvero) Examples:
  • go run ./cmd/mcp-announce --server weather --transport http --endpoint http://localhost:8089/mcp
  • go run ./cmd/mcp-announce --server local --transport stdio -- bash ./scripts/mcp-server.sh

cmd/mcp-code-exec​

mcp-code-exec is a long-running MCP server and is configured by:

  • MCP_CODE_EXEC_PORT (default 8080)
  • MCP_CODE_EXEC_TIMEOUT (default 30s)
  • MCP_CODE_EXEC_MAX_OUTPUT (default 1048576) Examples:
  • MCP_CODE_EXEC_PORT=8088 go run ./cmd/mcp-code-exec

cmd/openapi-export​

  • --o output file path (default stdout) Examples:
  • go run ./cmd/openapi-export --o docs/openapi/openapi.json

cmd/pii-model​

Subcommands:

  • download
  • status
  • clean Examples:
  • go run ./cmd/pii-model status

cmd/pii-scan​

  • --text inline text to scan
  • --dir directory to scan
  • --boundary policy boundary (default output)
  • --json output JSON
  • --verbose include detailed findings Examples:
  • go run ./cmd/pii-scan --text "contact me at [email protected]" --json

cmd/prompt-dataset​

  • --list, --get, --create, --add-entries
  • --dataset dataset id for --add-entries
  • --from-logs, --prompt-hash, --since, --max-entries, --failures-only
  • --name, --version, --tenant Examples:
  • go run ./cmd/prompt-dataset --list --tenant default

cmd/prompt-diff​

  • --prompt, --from, --to, --tenant, --json Examples:
  • go run ./cmd/prompt-diff --prompt support_prompt --from 2 --to 3 --json

cmd/prompt-eval​

  • --dataset, --dataset-version, --prompt-hash
  • --scorers, --threshold
  • --baseline-run, --regression-baseline, --fail-on-regression
  • --notify, --notify-subject
  • --format, --ci, --github-summary, --json, --tenant Examples:
  • go run ./cmd/prompt-eval --dataset release-gate --prompt-hash abc123 --fail-on-regression --format markdown

cmd/prompt-experiment​

  • --list, --get, --create, --complete, --winner, --tenant Examples:
  • go run ./cmd/prompt-experiment --list --tenant default

cmd/prompt-tools​

Meta-dispatcher subcommands:

  • eval (prompt-eval)
  • dataset (prompt-dataset)
  • experiment (prompt-experiment)
  • diff (prompt-diff) Examples:
  • go run ./cmd/prompt-tools eval --dataset release-gate --prompt-hash abc123

cmd/quota​

Subcommands:

  • status: --tenant, --json
  • reset: --tenant, --window (minute|hour|day)
  • override: --tenant, --field (rpm|rph|tpm|tph|tpd|cost), --value, --expires, --clear Examples:
  • go run ./cmd/quota status --tenant default --json
  • go run ./cmd/quota override --tenant default --field rpm --value 120 --expires 1h

cmd/run-feedback​

Subcommands:

  • submit: --workflow (required), --rating (1|-1 required), --comment, --user, --tenant, --tool-chain
  • list: --workflow (required), --limit (default 20), --format (table|json), --tenant Examples:
  • go run ./cmd/run-feedback submit --workflow run-123 --rating 1 --comment "Outcome was correct"
  • go run ./cmd/run-feedback list --workflow run-123 --format json

cmd/tenant​

Subcommands:

  • create: --id (required), plus tenant config/rate-limit flags
  • get: --id (required)
  • list
  • update: --id (required), mutable tenant config/rate-limit flags, --enabled
  • disable: --id (required) Examples:
  • go run ./cmd/tenant create --id acme --display-name "Acme Inc." --llm-provider openai
  • go run ./cmd/tenant update --id acme --enabled false

cmd/tool-feedback​

Subcommands:

  • submit: --tool (required), --rating (0.0-1.0 required), --comment, --tenant, --user
  • list: --tool (required), --limit, --format, --tenant
  • metrics: --tool or --degraded, --threshold, --format, --tenant Examples:
  • go run ./cmd/tool-feedback submit --tool http_get --rating 0.9 --comment "Stable"
  • go run ./cmd/tool-feedback metrics --degraded --threshold 0.4