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.

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-exec​

This tool is invoked via workflows and does not have a standalone CLI entrypoint.

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)