CLI Reference

caco is the single entrypoint for all Cacophony operations. It supports binary alias resolution, JSON help, and JSON output on every command.

Global Flags

Binary Alias Resolution

Cacophony supports binary aliases that resolve into the caco command tree:

caco_bd          → caco bd
caco_agent_new   → caco agent new
caco_bd-v2       → caco bd-v2    # hyphens stay within segments

Project Resolution

Project-scoped commands that allow omitting --project resolve in this order: explicit --project, CACO_PROJECT, CACOPHONY_PROJECT, top-level default_project, then the legacy first configured project fallback. Omitting --project means “use the resolved project,” not “search every configured project.” Commands aggregate globally only when they are inherently fleet/global surfaces or expose an explicit opt-in such as --all-projects. Runtime shorthand commands such as caco claude intentionally remain stricter and require an explicit project or runtime-specific interactive default.

Passthrough Commands

Commands that wrap another tool, including caco shell, caco exec, caco ssh, caco scp, and caco mosh, preserve wrapped-tool arguments after the Cacophony command path is resolved. Use an explicit -- separator when the remote command or its first argument may look like a Cacophony flag, for example caco @worker-1 exec -- grep -R pattern .. Unknown long options on passthrough commands are delivered to the wrapped tool instead of being rejected as unsupported Cacophony flags. First-party remote caco dispatch and multi-node fan-out wrap the remote command as exec ..., replacing the remote login shell with the managed child so interactive attaches and fleet commands do not leave an extra shell process behind under sshd-session.

Command Families

caco agent — Agent Lifecycle

caco attach / caco a — Attach to an Existing Agent

caco attach without a target opens a fuzzy-filterable numbered picker showing short name, project, node, state and ID, including visiting agents. Type a filter, then a number to attach; / resets and q or EOF cancels without changing a session. No external picker program is required. JSON or non-terminal invocations list candidates without prompting, even with one candidate.

caco a @cltv-switcher, caco attach research and caco agent attach @caco-ctrl share agent resolution: exact ID, exact short/declaration/persistent name, unique prefix, then unique fuzzy subsequence match. Ties list candidates and exit nonzero; the current project never silently breaks a tie. Use --id <exact-id> to bypass name lookup. Attachment reuses the existing backend, --raw and --no-gfx; JSON/pipes return metadata rather than opening a terminal. Nested agent attach retains its environment-ID default, but top-level attach/a always picks when no target is supplied.

Bare caco @x resolves across agents, configured nodes (including short names), and projects: exact matches beat prefixes, which beat fuzzy matches. A unique agent attaches; a node/project opens its TUI. Equal-rank collisions list matches and require @agent:, @node:, or @project:. With a subcommand, caco @node status remains node routing even when an agent/project shares the name. TUI references such as caco tui @project:view, @project#view, and @node:project#view retain workspace/view selection; an existing node wins the legacy colon form. See attach entrypoints and matching for inventory and offline behavior.

caco pi / pico / pi-client — Managed Pi-Family Agent Launch

caco bd — Beads (Task Management)

For scripting, caco bd snapshot list --json now uses the canonical {ok,data,meta} envelope: snapshot rows live under data.entries, while meta carries the project, snapshot root, and count.

No-ID caco bd claim keeps explicit ownership and specialist workflows intact while reducing out-of-lane churn: generic workers prefer non-specialist ready work before obvious Android, companion, web/caco-web, macOS, or macOS-app beads when both are ready; explicit --bead-id claims and surface-specialist agents are unaffected, and specialist-surface beads are still claimable when they are the only ready work. Generic no-ID claim also skips coordination parent beads and live ops/doctor checkout-drift repair beads unless they are explicitly assigned. When no ready bead is claimable, the structured no_ready_beads error includes exclusion counts and bounded excluded_sample_ids for the skipped buckets so operators can inspect representative open/permanent beads without a separate broad search.

Worker-spawn surfaces, including caco bd dispatch and queued pickup, refuse EPIC/umbrella records encoded as type: epic, a [EPIC] title prefix, or an epic label. Dispatch child beads instead. caco bd create --claim true preserves create-and-claim intent through server-side handling and forwarded/outbox replay; successful output may say created and claimed. If create/claim reports indeterminate_create, indeterminate_claim, claim_after_create_unverified, or claim_after_create_error, inspect the matched bead state before retrying so restart-window transport failures do not create duplicates or double-staff work.

For beads-primary convergence after a config change or restart, run caco bd trigger-vote --dry-run first. The preview prints the active primary, preferred candidate order, intended-primary views by node, reachability/maintenance state, current term, and the action that would be emitted. Running without --dry-run reuses the normal vote/switch feed events to nudge peers toward the canonical primary and refuses with a structured unreachable-authority error instead of forcing an unsafe failover.

caco blame — Bead-aware Git Blame

The blame helpers are read-only, command-runtime, MCP-enabled inspection tools. They parse ordinary commit prose such as : summary, , or Beads:; JSON output includes structured explanations when a line has no commit message, no bead ID, or unavailable bead metadata.

caco heartbeat — Managed-agent Heartbeat Runtime Controls

Policy composes agents.heartbeat, projects[].agents.heartbeat, node, and per-agent layers; each daemon schedules locally. Config/runtime off, paused, and terminal state suppress action. pi-heartbeat defaults to one role-aware action; CACO_PI_HEARTBEAT_PROMPT replaces it and explicit observe-only records receipts. Controls use /api/v1/heartbeat*; remote scopes use caco @node/@all.

caco file — Project File Cache

The file cache stores blobs and JSONL metadata under the Cacophony runtime root by project. In the TUI, Project Files materializes available blobs into a sanitized Source-browser view so records open with the same tree/content, syntax highlighting, and image preview behavior as Project Source.

• Records: Records carry the generated file id, logical name, sha256, size, optional MIME type, tags, source node, source path, blob relative path, and availability.
• Adding files: caco file add refuses empty payloads unless --allow-empty true is supplied, deduplicates blob bytes by sha256, and can optionally broadcast first-party project message availability with --broadcast true. Before indexing, the final stored blob is checked against files.max_file_size (default 5MB); image inputs follow files.image_handling.default_behavior (preserve, compress, or reject) with optional auto_compress, compression_format, and compression_quality.
• Output and MCP: JSON output uses the standard {ok,data} envelope and includes base64 content for get. The generated MCP family is caco file mcp stdio, exposing caco_file_add, caco_file_get, caco_file_list, caco_file_search, caco_file_status, and caco_file_sync.
• Sync: caco file sync publishes/imports under .cacophony/files/<project>/ on the project state branch, validates sha256 before making blobs available, and refuses missing/corrupt blobs instead of marking them synced. Divergence recovery never resets local-ahead state: it requires exact reviewed OIDs, a clean descendant lineage, and push-capable mode; preserves the full local lineage under refs/cacophony/file-sync/preserved-local/<local-tip>; replays only typed newest project records, links, and verified blobs; and reports the backup ref plus reconciliation commit in JSON.

caco feed — Feed History Export

--since and --before accept RFC3339 timestamps or relative durations such as 30m, 3h, and 1d. --limit defaults to 500 and is capped at 5000. The command is MCP-enabled and agent-safe for inspection/export, but it writes the requested output file and therefore is not idempotent in the filesystem sense.

caco msg — Messaging

Message writes accept --body, --body-file <path>, or --body-stdin (--body-file - also reads stdin). File/stdin text is verbatim. Shell callers must use these safe inputs for Markdown, dollar expressions, quotes, or multiline text; MCP uses shell-free body/body_file.

caco msg send --target accepts canonical caller IDs, unambiguous current-project short IDs, and explicit @node: / @agent: targets. Bare and @agent: targets resolve through structured agent inventory when possible; rows with an owning node canonicalize to node:project:agent-id so direct inbox wake delivery uses the full caller key. Ambiguous matches fail closed.

In --json mode, msg send, msg reply, and msg broadcast return structured stdout errors (ok=false with missing_argument or invalid_argument) for missing required flags or blank bodies instead of plain stderr-only validation failures.

Options for caco msg speak:

• Personas: caco msg speak --persona <name> resolves declarative TTS personas from speech.tts.personas; explicit --voice / profile/model overrides still win, and unknown personas fail with unknown_tts_persona instead of silently falling back. When no explicit persona or voice is supplied, bounded sender/body heuristics can infer a configured persona category such as status, alert, clock, narrator, ambient, or operator and mark the speak feed payload with tts_category plus persona_source: inferred_category.
• Urgent and reply: caco msg speak --immediate marks urgent speech for playback-slot bypass; caco msg speak --wait-for-reply <duration> waits for audible TTS, announces the listening window, records the configured STT input for the bounded duration, stops recording, transcribes the chunk, and returns the transcript in the blocking response. The transcript is not inserted into inbox/chat/message history; use --json to receive the structured data.wait_for_reply object and structured errors when TTS, STT, or the microphone is unavailable.
• Emotion: Per-message Azure SSML emotion is available via caco msg speak --express-as <style> (for example cheerful, excited, whispering, sad, angry, calm; none disables) with an optional --styledegree (0.01–2.0); like the per-message --voice-filter override, it takes priority over the configured express-as profile rotation for that one message and is ignored for non-Azure models.

caco loop — Repeated Narration

The browser dashboard chat composer has a separate chat-context slash command for recurring messages: /loop <interval> <message>, with /loop status and /loop off for inspection and cancellation.

caco ops — Bounded Operations Snapshot

Ops collectors share one deadline and drain independently, so one timeout does not degrade healthy inputs. JSON is compact by default while retaining totals, truncation flags, and class counts. Expand with --max-rows N, --max-findings N, or --include-details; --full is unbounded.

caco config — Configuration

caco config diff --node <peer> remains the cluster hash matrix filter. caco config diff <tag> is mutually exclusive with --node and compares the current local config VCS repo against the supplied checkpoint tag/ref. restore is mutating and refuses to run without --yes; after a restore, inspect caco config diff and restart or distribute only if the restored files are the intended runtime config. Sparse validation uses the installed/running caco implementation, so text and JSON output include a warning when that binary was built from a different commit than the checkout being inspected; rebuild/update the binary or use queued source tests before trusting just-edited sparse matching behavior.

caco mode — Execution Modes

Execution modes gate daemon automation policy such as auto-spawn / auto-claim; the mode-rule when predicate DSL is documented in the Execution Modes section of the configuration reference.

caco warmup-cache — Advisory Warmup Cache

The warmup-cache command family is an inspection surface over existing cache artifacts. Current public commands scan/list/show summaries only; lower-level generate/clear request helpers remain explicit data paths and do not make startup reuse automatic by themselves.

caco cert — Certificate Management

caco test — Queued Test Execution

Queued test metadata survives daemon restarts: queued jobs are re-pended, and an in-flight test job now survives a restart (durable-jobs S3b) — re-adopted if still running, or finalized from its durable exit_status file if it finished while the daemon was down — with a retryable infrastructure error record (failure_kind: "daemon_restart_recovered", artifact paths, recovery hints, retry_after_secs, retry_command) only as the fallback for an unrecoverable job.

• Zero tests: Cargo-test jobs that execute zero filtered tests fail by default; set CACO_ALLOW_ZERO_EXECUTED_CARGO_TESTS=1 or legacy CACO_ALLOW_ZERO_TESTS=1 only for intentional zero-test probes.
• Disk exhaustion: Queue output containing ENOSPC / No space left on device is classified as retryable failure_kind: "disk_exhaustion". Free space with the prune commands (from a managed worker, add --current-agent to touch only its own caches), or retry with an isolated CARGO_TARGET_DIR.
• Progress: While caco test run --wait is queued or running, human-readable output reports queue position and running count when available, and JSON timeouts include data.wait_progress. Running jobs expose an early caco test logs stderr progress marker before child output exists.
• Timeouts: Test timeouts terminate the isolated child process group, not just the shell/cargo wrapper.
• Parallelism: Queued cargo commands are capped by the queue runner (a core-count-proportional default of floor(nproc/2) clamped to floor 2 / default max 4, with macOS pinned to the floor; override the value with CACO_QUEUED_CARGO_BUILD_JOBS or raise the clamp with CACO_QUEUED_CARGO_BUILD_JOBS_MAX): missing CARGO_BUILD_JOBS and RUST_TEST_THREADS defaults are injected, and over-cap --test-threads, --jobs, or -j flags are clamped so free-form cargo/clippy/test jobs do not oversubscribe shared hosts.

caco build — Queued Build Execution

Queued build metadata is durable across daemon restarts, and in-flight detached build jobs now survive a restart (durable-jobs S3): queued work is re-pended, a still-running build is re-adopted, a build that finished while the daemon was down is finalized from its durable exit_status file (recovering the real pass/fail), a genuinely-stranded orphan is reaped, and only an unrecoverable build falls back to a retryable daemon_restart_recovered infrastructure error; unavailable recovered job IDs report retryable queue_job_unavailable JSON errors rather than unstructured polling failures. caco build run --timeout <seconds> stores a request-level runtime override on the job; 0 and non-integers are rejected. While caco build run --wait is still queued or running, human-readable output periodically reports queue placement and JSON timeout output includes data.wait_progress when the queue list is available. Running builds also expose a stderr progress marker through caco build logs before terminal output exists. Build timeouts use the same process-group cleanup so compiler/build descendants do not remain running after the job is marked terminal.

caco pr — Product Pull Requests

caco pr list [--project <project>] [--needs-review] classifies open PRs by their next action: ready, draft, conflict, behind-base, checks-failed, checks-pending, changes-requested, review-pending, review-never-requested, or an unknown blocked state. It uses the configured project repository and gh wrapper, and preserves requested reviewers plus failed and pending check names in JSON.

caco pr exposes three distinct worktree flows.

• Checkout: caco pr checkout <N> [--project <project>] creates a new managed in-project agent whose pr_branch checkout tracks an existing live PR head; it requires the project’s GitHub-integration opt-in, an effective pull-request backend, PR target, allowed origin push path, and a same-project head repository.
• Adopt: caco pr adopt --pr <N> --bead-id <bd-id> lets the current authorized worker preserve its ordinary checkout while creating a Cacophony-owned subordinate exact-head checkout; adoption records prior/new owner, PR, bead, generation, checkout paths, and clean ambient branch/HEAD/upstream divergence. Dry-run preserves ambient ahead commits and emits an --adoption-receipt required for real clone; clone/fetch/checkout records bounded phase/PID/error and exact partial resume; sync-main merges rather than rewrites the adopted head, and push is verified same-PR/non-force only.
• Explicit checkout: An explicit isolated source uses caco agent reintegrate --project ... --checkout ... --dry-run; real direct/local-merge publication requires the emitted --checkout-receipt, binding the actual bead/ownership mode/allowed operational paths/branch/HEAD/path/target instead of the ambient agent branch. Metadata-less shared worktrees require the same Git common directory and an explicit authoritative --bead-id when assignment is ambiguous.
• Init: caco pr init --repo <owner/repo> --base main --name <slug> [--resume] instead creates or resumes a bounded product worktree initialization: sibling metadata records phase/PID/attempt/error before clone, status prints liveness and the exact recovery command, and .caco-pr.json is written only when ready. apply, push, and sync-main operate only on that product worktree and keep Cacophony operational state out.

caco scratch — Scratchpad Notes

--json missing args return missing_argument.

caco tmux — Tmux Management

caco tmux send detects whether a pane is in copy mode (or another non-normal mode) and exits it before sending keys. This prevents accidental socket death from keystrokes interpreted as copy-mode or tmux command-mode commands.

caco choices — Operator Choices

caco sidecar — Sidecar Management

caco tts — Text-to-Speech Services

For scripting, caco tts status --json and caco tts io output show --json use the standard {ok,data,meta} envelope.

• Status fields: Status JSON includes runtime_muted, mute_source, mute_reason and mute_control, plus spoken_name_snapshot health (endpoint, cached count, failures, last status and error, next retry). status --explain AGENT --json adds a runtime object that says whether silence came from runtime mute or a config rule, and whether spoken-name lookup is degraded. Spoken names come from the lightweight /api/v1/beads/spoken-names projection, so snapshot backpressure doesn't block them.
• Runtime mute: Runtime mute is daemon-owned runtime state: unscoped mute/unmute affect only the local node by default; pass --all to broadcast tts_runtime_control and converge on peer TTS daemons, or use @node routing for selected-node control.
• Agent authority: Agent-initiated runtime mute changes are authority-gated by speech.agent_mute_control : worker and project_controller scopes are always denied the runtime mute-family (caco tts mute / unmute / toggle-mute); the default cluster_controller mode lets a cluster-controller agent flip runtime mute (the doctor auto-unmute-for-repair path), while operator_only denies even a cluster_controller so a deliberately-muted node stays muted against any agent. Operator and node credentials always bypass the gate, and operator/config-backed declarative mute rules remain authoritative.
• Persistence: Each node persists its local mute bit across daemon/TTS restarts; use scoped mute rules for durable config policy by project, node, surface, profile, role, name, or agent.
• Skips: TTS requests blocked by intentional mute policy are expected skips: traces record outcome=skipped / rule=audio-muted, the message can be acknowledged, and the daemon does not count it as a synthesis/playback failure.
• Caller identity: For feed-driven speech, the headless TTS daemon forwards the originating sender as X-Caco-Caller; muted-policy traces, tts status --explain, and audit diagnostics should name the real agent or inner payload sender when known. A visible node-token caller on agent-authored speech is an authentication fallback leaking into diagnostics, not the expected operator-facing identity.

caco tui — Terminal UI

See TUI documentation for details.

caco web — Web Dashboard

PORT="11180"
caco web --port "$PORT"

Run the web dashboard — an axum HTTP server with embedded static assets and an API proxy to the local daemon (default port: 11180).

Restart/backend 5xx ⇒ Backend unavailable; timeout ⇒ Snapshot delayed; snapshot upstream 5xx ⇒ 200 OK daemon_proxy_upstream_error with upstream_status. Dev: cargo run -p caco-web --bin caco-web-dev-server -- --port 0. Observe: cargo run -p caco-web --bin caco-web-observe -- --url "$URL" --comprehensive --out "$OUT" --audit-md "$AUDIT_MD"; scenario: --scenario summaries-slow-list delays /api/v1/summaries. --skip-build needs a fresh dev-server for Rust/server changes; static dashboard assets are served live from the checkout. Set CACO_WEB_OBSERVE_CHROMIUM when Chrome is off PATH; the default Nix dev shell provides the Playwright helper but expects a host browser. Observe logs include served web version, proxied daemon version, and daemon URL; a version-skew warning means evidence may reflect the live daemon rather than only checkout caco-web code. Summaries default to project; the web proxy bounds summaries reads at 12 seconds, so cold histories show Loading…, then Still scanning… / retryable unavailable states instead of occupying daemon handlers for the daemon's longer summaries budget.

caco daemon — Node Daemon

caco daemon

Start the node daemon. Usually managed by caco up rather than invoked directly.

caco daemon validate

Side-effect-guarded daemon startup validation: loads config read-only, resolves the node, runs schema construction and DB migrations inside an owner-private temporary runtime, uses an in-memory non-credential sentinel instead of creating or reading a token file, disables validation-time config Git/fingerprint writes, removes temporary state, and proves configured high-risk path metadata plus Git HEAD remained unchanged. --json returns the real-start path plan, temporary artifact metadata, cleanup result, and configured-state guard receipt. Reports failure instead of validate ok if temporary cleanup fails or configured state changes.

Service Lifecycle

Extended Command Families

Less-common command families, fleet helpers, diagnostics, transport wrappers, release/update helpers, and onboarding commands now live on the companion Extended CLI Reference. The primary and extended pages form a single operator reference; their organization is for navigation rather than enforcement of a per-page byte limit.

JSON Help

Every command supports --help --json for machine-readable help:

caco agent new --help --json

{
  "command": "caco agent new",
  "summary": "Start a managed agent.",
  "args": [...],
  "subcommands": [],
  "runtime": { "kind": "command" },
  "mcp": { "enabled": true, "tools": [...] }
}