CLI Reference

One reference for the current cco CLI, grouped by what you do with it. Run cco <command> --help for the authoritative flag list.

Global flags

Placed before the command, for example cco --dry-run cleanup.

  • --version — show the cco version and exit.
  • --log-level — DEBUG, INFO, WARNING or ERROR (default INFO).
  • --log-file — path for structured JSON logs.
  • --dry-run — show what would be done without executing.
  • --no-color — disable colored output.
  • --yes, -y — skip confirmation prompts for destructive operations.

Guarded execution

cco run TASK

Guarded runner: launches an agent CLI, checks scope after the fact, verifies, then keeps or rolls back the change.

  • --repo — repository to run in (default .).
  • --task-class — route by task class via config runner.routing and escalate on retryable failures. Ignored, with a warning, when --executor is given.
  • --executor — claude, codex, opencode or command (default from config runner.default_executor).
  • --executor-cmd — command line used with --executor command.
  • --executor-sandbox — enable the executor's own sandbox; without it a claude run is reported as degraded.
  • --executor-model — model passed to the executor (ignored under routing, where tier models apply).
  • --executor-timeout-seconds — executor time limit (default 1800).
  • --max-budget-usd — spend cap passed to the executor.
  • --contract-file — CCI contract JSON or CCO contract YAML; --contract-id must match it when both are given.
  • --allow-file / --verify-command — ad hoc allowed file and argv-only verify command (both repeatable).
  • --json — machine-readable outcome. --no-redact disables PII redaction in run artifacts (debugging only).

cco trace RUN_ID

Inspect the artifacts of a completed run. Flags: --json (all artifacts), --format auto|json (json is the structured usage export).

cco cleanup

Delete old run artifacts according to the retention policy. Flags: --list (runs with age), --dry-run, --force (skip the automatic throttle), --json.

Configuration

cco config init

Write a supported config profile, or scaffold a per-project orchestration home.

  • --profile — direct-minimax (default), routed or routed-minimax.
  • --home PATH — scaffold config.yaml and runs/ at this path, then export CODIFIED_ORCHESTRATOR_HOME to use it.
  • --force — overwrite an existing config file.
  • --print — print the generated YAML instead of writing it.

cco config show

Show the current configuration. Flag: --json (API key variable names are redacted).

cco config list

List configuration profiles and mark the active one.

cco config switch PROFILE

Activate a profile.

cco config delete PROFILE

Delete a profile (asks for confirmation; the active profile cannot be deleted).

cco config tier [starter|pro]

Show the current tier, or switch to starter or pro.

Observability

cco observatory

Serve a read-only local dashboard of run artifacts.

  • --home — orchestrator home holding runs/ (default $CODIFIED_ORCHESTRATOR_HOME or ~/.codified-orchestrator).
  • --homes — extra homes as name=path,name2=path2; --home stays the default entry.
  • --port — TCP port (default 4173).
  • --host — interface to bind (default 127.0.0.1). Anything beyond localhost exposes run artifacts to anyone who can connect.
  • --legacy — serve the old observatory module instead of the runner view.

cco metrics

Show session statistics and coherence metrics. Flags: --json, --session ID, --store (persist current metrics in the memory store).

cco alert

List active alert rules (built-in and custom).

cco alert-add

Add a custom alert rule. Flags: --name, --condition, --threshold (all required) and --action (webhook URL or log, default log).

Health

cco doctor

Verify the cco installation and runtime dependencies. Flags: --repo (required), --json, --verbose, --scan-only (scan repository knowledge files, skip provider checks), --validate-refs (check cross-references in AGENTS.md, .context/*.md and docs/*.md).

cco schema

Show the contract and outcome schema versions and the executors this cco supports. Flag: --json.

cco version

Show the cco version. Flags: --verbose (Python, platform, executable), --json. cco help prints a short command list.

Planning and review

cco plan

Plan a task and generate a prompt bundle for review. Flags: --repo and --task (required), --json, --no-redact, --timeout-seconds, --preflight (run pre-flight checks first).

cco task

Execute a task; supported acceptance requires guarded, contract-linked execution. Flags: --repo and --task (required), --guarded, --allow-file, --verify-command, --contract-file, --contract-id, --verify-file, --allow-noop, --require-contract, --raw-debug, --no-memory, --timeout-seconds (guarded default 1800, 0 for no limit), --preflight, --json, --no-redact.

cco task-ready

Check whether a task is ready for guarded execution; exits 1 unless the state is ready. Flags: --repo and --task (required), --allow-file, --verify-command, --allow-noop, --json.

cco task-proof

Run proof cases that validate cco against fixture repositories. Flags: --profile (default direct-minimax), --case (default greeting-source; all runs every case), --suite (core), --timeout-seconds, --json.

cco review

Review uncommitted changes and generate a code review report. Flags: --repo (required), --since REF (default HEAD), --json.

cco ask QUERY

Ask an ad-hoc question to the configured primary model. Flags: --json (includes usage stats), --system-prompt, --temperature (0.0–2.0, default 0.1), --timeout-seconds.

Workstreams and branch tasks (beta)

Beta commands for tracking concurrent agent work. All accept --json unless noted.

Workstreams

  • cco workstream — prints the available subcommands and exits 1.
  • cco workstream-list — list workstreams; --active shows only pending/running.
  • cco workstream-create TASK REPO — create a workstream.
  • cco workstream-status ID — detailed status.
  • cco workstream-add-step ID DESCRIPTION AGENT_ROLE — add a step.
  • cco workstream-complete-step ID STEP_ID OUTCOME — complete a step; --artifacts takes comma-separated paths.
  • cco workstream-trigger-agent ID AGENT_ROLE — record that an agent was triggered.
  • cco workstream-set-state ID STATE — pending, running, completed, failed or abandoned.

Branch tasks

  • cco task-branch-start TASK REPO — start an isolated branch task; --parent for lineage, --branch for the name.
  • cco task-branch-finish TASK_ID OUTCOME — complete a branch task.
  • cco task-branch-abandon TASK_ID — abandon; --reason.
  • cco task-branch-list — list; --active shows only pending/active.
  • cco task-branch-status TASK_ID — detailed status.
  • cco task-branch-record-agent TASK_ID AGENT_ROLE ACTION — record an agent action; --result (no --json).

Other command groups

These sub-apps are also registered; use cco <group> --help for details.

  • cco tasks — start, finish, abandon, list (task branches tracked in the memory store).
  • cco mem — long-term memory store: add, ask, consolidate, status, list, project-switch, project-show, export, sync, suggest.
  • cco obsidian — sync, import, status.
  • cco codex — code intelligence: query, impact, context, suggest-agent, status, detect-changes.
  • cco webhook — add, list, remove.
  • cco usage — summary, export.
  • cco secret — list, backup, rotate.
  • cco audit — query, export.