Extended CLI Reference

This companion page keeps the main CLI Reference focused on common operator families while preserving the less-common command families, fleet helpers, diagnostics, transport helpers, and onboarding commands in the same reference style.

caco action — Configured Actions

Actions are operator-defined commands declared under projects.<name>.actions or global/node scopes. Args after -- are shell-escaped and appended. With resolved node/project context, action commands receive CACO_NODE, CACOPHONY_NODE, CACO_PROJECT, and CACOPHONY_PROJECT.

caco audio — Speech & Transcription

caco image — Image Generation

caco changelog — Release Changelog

caco log — Service Logs

For scripting, caco log exceptions --json returns the canonical {ok,data,meta} envelope: exception rows live under data.exceptions, while meta carries node, totals, component filter, and returned-count metadata.

caco event — Command Audit Log

caco notify — Notifications

caco notify send --json reports missing or whitespace-only titles as structured stdout errors with ok=false and error.code set to missing_argument or invalid_argument.

caco outbox — Cross-Node Write Outbox

caco decision-point — Decision-Point Rewind Previews

caco secret — Encrypted Secrets

caco secret

Manage encrypted secrets through the local daemon.

caco relay — Relay & Gateway

Useful for credential-light deploy shapes where a mesh bridge node forwards cluster traffic without needing full hosted-project secrets.

caco service — Native Lifecycle Supervisor

This is for inspecting the native service manager, not for routine daemon convergence. Use caco up/caco down/caco restart for that. caco service status --json reports healthy, health_state, and a repair hint/command when the supervisor is installed but not loaded, inactive, or failed; caco ops check surfaces the same condition for controller alerting. On launchd, caco service load enables the canonical label before bootstrap; bootstrap itself is the load/start operation, so load no longer follows with an immediate kickstart -k that could restart a just-launched supervisor during daemon/TTS/STT adoption. Disabled-label state and bootstrap failures still produce plist/domain-specific diagnostics instead of a generic native-command failure. Use caco service disable instead of raw launchctl/systemctl when the operator intentionally wants manual startup: it disables/unloads the supervisor, treats already-unloaded launchd bootout as success, and prints follow-up guidance to verify status and run caco up --skip-update if daemon/web/TTS services should remain running outside native supervision.

caco prune — Artifact Cleanup

caco cron — Scheduled Tasks

Use caco @<node> cron status --name <name> for a node-scoped scheduled driver. Status distinguishes healthy, running, failed, never_observed, and stalled; staleness is derived from the configured cron expression and the latest scheduled execution receipt or durable log activity.

A cron or action may declare check:, a shell command that exercises its prerequisites (identity, SSH key, pinned gh account, secret paths, tools) without side effects. Checks run in the real command's environment with CACO_CRON_CHECK=1 and write no cron receipt. Each daemon re-runs its own cron checks after every served config change and at least hourly, and reports only new failures to the errors feed.

A cron that declares project:, and every project-scoped action, runs as that project: it gets the project's environment (for example SOPS_AGE_KEY_FILE), the same GitHub routing an agent spawn gets, and the configured account's gh credential for the routed host. Inherited gh tokens are cleared and there is no fallback to the node's active account; the check fails when that environment does not resolve.

caco summary — Activity Summary

caco summary --since 3h

Print a high-level activity summary for a time period. Shows bead throughput, agent completions, and notable events. This singular command only accepts --since; recorded session summaries live under the plural caco summaries list / caco summaries show commands.

caco stats — Unified Fleet Stats

caco stats --window 7d --bucket day --json

Show the unified fleet stats aggregate from /api/v1/stats: the compute/storage rollup, per-node sysinfo, token usage by project, and bead throughput (closed-rate plus a closed-bead time-series for charts). Token usage preserves input/output/cache-read/cache-write totals and also reports cached versus fresh input and output. --project / --all-projects scope the throughput section (fleet-wide by default), --node narrows the per-node rows while the compute rollup stays whole, and --window (24h/7d/2w or a bare hour count, default 24h) with --bucket (hour/day) tune the throughput series. --json emits machine output and --gfx renders kitty graphics; the underlying endpoint is read-only and readable at worker and project-controller scope.

caco context-budget — Injected-Context Budget

caco context-budget --project cacophony

Show the per-declaration injected-context budget for a project: the shared AGENTS.md bytes plus each persistent-agent declaration's composed profile-stack bytes, so context-mass growth is visible. Because AGENTS.md is injected into every managed agent it dominates the budget; this read-only view is the companion to the caco ops AGENTS.md soft-budget watch (env CACO_OPS_AGENTS_MD_BUDGET_BYTES). --project defaults to CACO_PROJECT / CACOPHONY_PROJECT / the first configured project; --json emits machine output. Pass --record to also emit each declaration's total as a caco log perf event (component context-budget, metric injected_context_bytes, label = declaration) so injected-context growth is board-visible on a cadence. With --record, add --threshold <bytes> to record declarations whose total exceeds the budget at severity regression (and mark them [OVER BUDGET] in the text view) so context bloat surfaces as a regression rather than plain info.

caco ps — Process Listing

PROJECT="cacophony"
NODE="primary-node"
caco ps --project "$PROJECT" --kind agent --state running --node "$NODE"

List services, sidecars, and agents, with PID/uptime when known. Terminal agents are hidden unless --state is set.

caco ls — Runtime Directories

PROJECT="cacophony"
AGENT_ID="agent-id"
caco ls --project "$PROJECT" --kind agents --agent "$AGENT_ID"

List owned runtime directories and checkout roots. Useful for understanding the on-disk layout of a running Cacophony installation.

caco bd daemon — Standalone Beads Service

caco mcp — MCP Gateway

caco mcp stdio

Start the aggregate MCP stdio server. See MCP Integration for details.

caco update — Self-Update and Companion Updates

caco launcher — Launcher Archive

Manage the launcher binary archive for multi-version rollback. When a launcher is promoted from pending to active, the outgoing binary is archived. If health checks fail after a restart, the rollback path walks the archive from newest to oldest until a healthy daemon is restored. The default retention cap is one previous rollback generation; live archived launcher binaries are retained beyond that cap and reported until their process exits.

caco node — Node Inspection

caco foreach — Fleet-Wide Commands

caco doctor — Diagnostics

caco doctor

Diagnose local and mesh health: daemon, sidecar, beads host/listener reachability, config hash parity, peers, PKI, lifecycle test fake-daemons, stale agents, release-capable GitHub Actions runner health when gh works, and more. Supports --json.

• Beads: Bead-count divergence probes are batched across projects/peers. Beads-primary rows can trust a successful local /api/v1/beads/status authority probe so stale peer snapshots do not mark a working primary down.
• Agents: Accounting-only/watch stale-agent rows stay separate from actionable stuck-agent errors.
• Storage: Storage hints prefer retention/VACUUM and targeted cleanup; an oversized daemon-fts.db is probed read-only for SQLite page/freelist evidence so a large compact search corpus stays informational, while reclaimable fragmentation, an unavailable compactness probe, or an oversized WAL remains actionable without recommending a manual live-store VACUUM.
• macOS release runner: For the shared macOS release runner, use caco action run --project cacophony github-runner-status--ms-mac for status and node-routed caco @ms-mac action run --project cacophony restart-github-runner--ms-mac for the approved repair; when the status action is routed to ms-mac, it also prints best-effort LaunchDaemon ownership, rescue tmux runner sessions, and runner processes so operators can distinguish the permanent service from incident-only rescue sessions. The persistent update-helper profile may invoke that repair when Release binaries are queued on an offline ms-mac runner. The repair requires each listener to remain running across two bounded launchd observations, emits launchd and log diagnostics after another exit, and narrowly resets the cacophony-ms-mac credential state when its logs prove GitHub deleted the registration so the Nix-managed startup path can register it again.
• Routing: Routed command failures preserve bounded remote stdout when a JSON action returns useful diagnostics there with empty SSH stderr.

caco doctor feed checks the feed ledger: it scans the active feed JSONL (or --path), reports malformed or non-UTF-8 lines (bounded by --max-findings), and rewrites a damaged ledger only with --repair --yes.

Deep-doctor findings (stale tmux sessions, agent directories, lifecycle locks, config hashes, feed and index counters, performance) are read-only and never run cleanup or restarts. Each finding has a severity, a subject, up to six evidence lines and, where one is safe, a repair command:

• Text: [severity] kind: subject or severity metric value unit subject, then evidence and an optional repair: line; <no performance findings> or <no stale-state findings> when empty.
• JSON: stable kind/metric, severity, value, unit, subject, evidence.shown/evidence.omitted and nullable safe_repair_command; [] when empty.

caco bisect — Bead-aware Regression Bisect

Bead-aware regression bisect drives a good/bad search over a supplied set of candidate commits to find the change that introduced a regression for a bead. start takes a required --test-command (exit 0 = good, non-zero = bad) and a --candidates-file (a JSON array of {commit, bead_ids, summary} objects); each run checks out the next candidate in an isolated worktree, runs the test, and records the outcome, narrowing toward the guilty commit and surfacing the bead IDs its message references. status reports progress and guilty-bead links; reset clears the state. Supports --json.

caco microvm — MicroVM Worker Capability

caco microvm preflight is read-only and provider-neutral. It checks KVM, tun/tap, vsock, cgroup v2, nftables, supported hypervisor binaries such as cloud-hypervisor, and the microVM cache root. Treat ready=false as a placement blocker until the reported remediation hints are resolved.

For the reusable secret-free guest, build .#caco-microvm-agent-image-info and follow its kernel/initrd/rootfs env values. caco microvm node status reports state-dir, preflight, and cert contract without booting. caco microvm node up --dry-run runs launch preparation and tells you whether a real boot would be refused. On a ready Linux/KVM host, caco microvm node up wraps the repo-owned boot-proof harness in detached keep-running mode, records launcher.json, and leaves live boot/readiness details in the boot report; caco microvm node down stops the registered tmux session, runs runner shutdown when present, clears the launcher marker, and leaves state for the next launch; caco microvm node destroy previews by default and deletes that state only with --force. See micro-0 full-node microVM rollout for the current KVM host, boot-proof, and validation steps.

caco microvm validate checks a caco.microvm.validation.v1 JSON or YAML report from a microVM runner. It passes only when:

• host paths outside the declared --projected-mount values are denied;
• Docker, Podman and ssh-agent sockets are unreachable unless allowed with --allow-host-socket;
• daemon agent and project auth boundaries hold;
• CPU, memory and disk probes hit their configured limits;
• tap, vsock and cgroup cleanup leaves nothing behind, and startup and teardown timings are present.

Reports share one format across Cloud Hypervisor, Firecracker and Kata (RuntimeClass) runs: benchmark phases, denial probes, pass/fail/skip counts and short log excerpts, never secrets. For Kata, one managed agent maps to one pod labelled with its project, node, agent, bead and isolation; secrets stay as projected files or named environment handles; and a fallback reports both the requested kata and the backend actually used. The validator only classifies evidence; it never launches or changes Kubernetes resources.

--template prints a sample report, --report "$REPORT" --output microvm-validation-summary.json writes the summary, and --json prints JSON. A missing --report under --json returns a missing_argument envelope; validation failures exit with code 2.

just microvm-dispatch-integration is the first-party Docker-free two-node dispatch-lane scaffold. It prepares hermetic local git/profile inputs, records Linux/KVM/preflight skip evidence unless --require is used, writes alpha/beta configs and runtime projections, and produces a bounded evidence directory with VM network, asset, execution-plan, and runbook receipts. In --execute mode the current lane reaches daemon-status checks, beads-routing checks, and a hermetic dispatch-enqueue check before stopping explicitly at the remaining worker-pickup/completion boundary; it must not fall back to production ports or external credentials.

caco release — Release Management

Release jobs are reconciled with their real execution after a daemon restart rather than blindly restarted.

• GitHub jobs: Queued jobs return to the FIFO. A GitHub-strategy job durably records dispatch intent before invoking the workflow and persists its uniquely correlated Actions run ID before polling. Restart re-polls that run; if restart fell in the dispatch-to-ID gap, the daemon boundedly correlates exactly one workflow/ref/commit/time-window run and re-polls it without redispatching, while missing or ambiguous matches become restart-recovered errors.
• Legacy repair: caco release refresh also repairs the narrowly identifiable legacy gha-* false restart error caused by a missing durable run handle, while preserving unrelated terminal history.
• Node jobs: Node/local jobs re-adopt a still-live detached build or publish leader, or recover a completed phase from its durable exit status. An idempotent build phase may be restarted only when neither live-process nor exit-status evidence survives.
• Publish: The side-effectful publish phase is never blindly re-run: if it cannot be re-adopted or finalized from durable evidence, the job becomes a restart-recovered error with a manual verification hint to avoid a double publish (external product contract §17.7.7).

caco project — Project Management

caco pr — Product Pull Request Worktrees

Publish ready-for-review by default. Drafts are only for source that must not merge yet: explicit operator-requested review/RFC, experiments, or projects whose integration.default_intent is upstream_draft_pr. Pending parent/umbrella acceptance, unrelated CI, or live acceptance are not reasons to draft.

For a deliberate draft, use caco pr push --draft --draft-reason "Operator-requested RFC; do not merge yet" --title "..." --body-file body.md. A non-empty, single-line --draft-reason is required unless upstream_draft_pr supplies the project-intent reason. The reason is recorded in the PR body and publication receipt; caco pr list shows drafts separately, including missing or unavailable reasons. Existing PR readiness is preserved; changing draft state is a separate owner decision.

caco profile — Profile Inspection

caco checkout — Canonical Checkout Maintenance

caco checkout manages disposable canonical project caches. caco checkout status --project <name> distinguishes absent, empty, placeholder, partial, preservation-sensitive, policy-excluded, and valid shapes and prints the exact next action. A controller/operator uses caco checkout refresh --project <name> to atomically materialize a proven-clean shape. Use caco checkout regenerate --project <name> only after inspecting preserved dirty/local-only evidence; it is the first-party repair path instead of raw rm -rf, remote edits, manual reclone, or hand-written live-config repair. In agent contexts mutating subcommands may be hidden; use caco ls --kind checkout for read-only checkout inspection.

caco warmup-cache — Advisory Warmup Cache Inspection

Warmup-cache helpers normalize generate/list/show/clear requests and can explicitly delete selected cache artifacts through clear plans, but the shipped public CLI branch currently exposes read-only list and show. Treat it as advisory cache inspection, not automatic session extraction, prompt injection, or startup context reuse.

caco fleet — Fleet Snapshots

caco codespace — GitHub Codespaces Nodes

Manage GitHub Codespaces enrolled as Cacophony nodes. Operator shells expose lifecycle subcommands such as new, ls, stop, resume, revoke, remove, rekey, and enroll; agent contexts may hide mutating entries. Read-only inspection adds caco codespace status (the desired-vs-real pool view) and caco codespace reconcile --dry-run (the reconcile plan), both pure inspection over declared codespace_nodes pools with no cloud mutation. caco codespace new --source-repo <url-or-owner/repo> (or CACO_CODESPACE_SOURCE_REPO) selects the Cacophony source cloned/installed during remote bootstrap, defaulting to the upstream repository. There is no shipped caco codespace secret push/list/remove surface yet; use GitHub Codespaces user secrets or the repo-owned container secret-file path documented in the Codespaces guide.

caco stt — Speech-to-Text Diagnostics and Daemon Control

caco ambient-narration — Ambient Narration Controls

caco timeline — Activity Timeline

Aggregates commit/changelog/bead activity. Defaults to 48h or 100 commits; tune with --max-age-hours, --min-commits, --limit, and PROJECT="cacophony"; caco timeline --scope project --project "$PROJECT". --json errors return envelopes.

caco summaries — Session Summaries

summaries list and summaries show use a bounded CLI HTTP client (20-second request budget plus a short connect timeout) so a slow or unhealthy summaries endpoint returns a retryable summaries-specific error instead of hanging the terminal. When the daemon health probe still succeeds, startup/context-rehydration errors include a local managed-checkout fallback hint for .cacophony/agent/.../summary/*/summary.md.

caco operator-actions — Operator-Required Tasks

caco tendril — Tendril-Adjacent Operator Helpers

caco tendril watch watches recorded-summary screenshot artefacts (.cacophony/agent/*/summary/*/screenshots/*) across runtime agent checkouts, supports --project and repeatable --agent filters, skips already-present images unless --include-existing is supplied, and renders new or updated screenshots inline with kitten icat when available. Actual computer-control actions still use the separate tendril CLI (tendril list --json, WINDOW_ID="window-id"; tendril capture --window "$WINDOW_ID", DSL='hold(ctrl),c,release(ctrl)'; tendril run --window "$WINDOW_ID" "$DSL") or managed Pi Tendril MCP tools (tendril_list, tendril_capture, tendril_run, tendril_listen). For visual audits, list targets immediately before acting, capture before input, run one small Tendril action with waits, then capture again to verify the result. Preserve the JSON error envelope when capture fails: a target can be listed with capture=true while Wayland xdg-desktop-portal or another platform screenshot backend still times out or denies capture.

caco bootstrap — Developer Onboarding

Node-Aware Transport Helpers (cacophony-spec section 8.1.2)

Canonical wrappers around SSH-family transport that resolve node connection details from config:

All three commands support --print to show the resolved command without executing, and --json for structured output. Static OpenSSH commands never auto-accept unknown keys. Configure nodes[].ssh.host_key_fingerprint with an independently verified OpenSSH SHA-256 fingerprint before enrollment; a scan mismatch changes nothing. Noninteractive @node status/update/restart routing runs a bounded BatchMode=yes no-op preflight first, reports typed askpass, unknown-key, changed-key, network, authentication, or remote-command failures, and starts no requested update when preflight fails. Interactive caco ssh may still use the operator TTY for authentication but retains strict host-key checking. When these helpers or the @node shorthand run a first-party remote caco command, the remote shell string is prefixed with exec so the login shell is replaced by the managed child instead of lingering under sshd-session after the command exits.

These helpers are valid for static nodes whose config includes a host field and optional ssh metadata. They also have a first-party GitHub Codespaces exception: caco ssh cs-<hash> resolves the derived Codespace node ID through caco codespace ls and delegates to gh codespace ssh. Other dynamic/container nodes fail with a clear error unless their template declares an explicit SSH transport contract.

Operator Access for Dynamic/Container Nodes

Dynamic and container nodes (those matching a dynamic_nodes template) do not imply SSH reachability. There is no sshd or authorized_keys path on these nodes by default. SSH-based commands (caco ssh, caco mosh, caco scp, caco tui --node) fail explicitly when targeting a generic dynamic node, with an error message explaining the supported alternatives. GitHub Codespaces are the explicit exception: caco ssh cs-<hash> and caco @cs-<hash> tui use gh codespace ssh after resolving the live Codespace name from caco codespace ls.

Supported inspection and debug paths

What does not work for dynamic nodes

• NODE="dynamic-node"; caco ssh "$NODE" — fails with a clear error for generic dynamic nodes. Codespace nodes are the exception: caco ssh cs-<hash> delegates to gh codespace ssh.
• NODE="dynamic-node"; caco mosh "$NODE" — fails with a clear error
• NODE="dynamic-node"; REMOTE_PATH="/tmp/file"; caco scp "$NODE:$REMOTE_PATH" . — fails with a clear error
• NODE="dynamic-node"; caco tui --node "$NODE" — fails (delegates to caco ssh)
• NODE="dynamic-node"; caco cert distribute --node "$NODE" — use caco cert issue or caco node join bootstrap path instead
• caco foreach node ssh ... — only iterates static nodes; dynamic nodes are not included
• KUBE_CONTEXT="example-aks"; caco "@cluster:${KUBE_CONTEXT}" tui — works only for Kubernetes-hosted clusters reachable through the caller's kubeconfig; it is private exec, not generic dynamic-node SSH, and non-interactive runs can fail with the expected Unable to use a TTY message

Future work

Generic SSH or platform-exec transport for arbitrary dynamic/container nodes remains future work. The current @cluster:<kube-context>[/namespace] target is Kubernetes-specific private exec, and the Codespace path is GitHub-specific gh codespace ssh routing; broader support should use an explicit remote-exec transport contract, not silently assume container sshd. See cacophony-spec section 8.1.2 and cacophony-spec section 6.5.9.

caco version — Version

caco version

Print the caco version. Supports --json for structured output.

caco hooks — Webhook Ingress

caco hooks list
caco hooks show <scope>/<id>
caco hooks test <scope>/<id> --body ...

Inspect configured webhook ingress handlers (tokens redacted) and invoke one locally, bypassing HTTP. Distinct from project lifecycle hooks automation; see the webhook ingress contract.

caco link — Link Artifacts

caco link add --url ...
caco link list / show / search
caco link update / delete / sync

Manage first-class URL/link artifacts with bounded metadata, bead/agent associations, and freshness. Internal cluster-API URLs are refused in user-facing url fields.

caco plans — Plans

caco plans list / show

Inspect bead-linked plans surfaced across web/macOS/Android/iOS detail views.

caco search — Search

caco search <query>

Cross-surface bead/content search backed by the daemon search index.

caco suggest — Operator Suggestions

caco suggest list / show

Read node-local suggestion sets; suggesting never runs anything and each option runs at most once. Backed by the daemon /api/v1/suggest* endpoints.

caco remediation — Remediation Status

caco remediation status --json

Show current agent/queue remediation diagnostics (idle, stuck, zombie, rate-limited, frozen).

caco pi / caco pico / caco codex — Runtime Backends

caco pi       # launch a managed Pi agent runtime
caco pico     # launch a managed Pico agent runtime
caco codex    # launch a managed Codex runtime
pico          # launch the separate unmanaged standalone Pico TUI

Runtime-backend entrypoints. caco pico --managed remains a no-op compatibility alias for caco pico; the daemon's internal --managed --host <socket> activation still starts the embedded backing host rather than recursively creating another agent. Interactive Pi-family launches open the accepted agent ID in standalone chrome immediately, show a starting placeholder while runtime and attach metadata continue asynchronously, and promote the same pane from daemon snapshot/SSE state. JSON and non-interactive callers receive the accepted result for status or later attach.

caco pi-daemon — Standalone Pi SDK Host

caco pi-daemon status

Read-only probe of the separately supervised, opt-in Pi SDK host through the local daemon. Unconfigured nodes report configured: false; configured nodes report independent bounded socket, authenticated API, and embedded Dashboard reachability, nonsecret URLs, readiness, host instance, event, and session counts or typed retryable failure without exposing bearer contents, credentials, prompts, or output. Remote-node inspection uses ordinary caco @node pi-daemon status routing. The internal caco pi-daemon serve entrypoint is lifecycle-owned and starts the optional API and Dashboard in that same supervised process, not an ad-hoc web process.

caco chat / caco inbox — TUI Shortcuts

caco chat
caco inbox

Shortcuts into the TUI runtime focused on chat or inbox, not separate frontends.

caco macos — macOS Companion

caco update macos --dry-run / --install

Pull, sha256-verify, and install the macOS companion app from the matching release.

caco supervise / caco token

caco supervise            # native lifecycle supervisor loop

Lifecycle supervisor entrypoint and node-token material (see caco service and the release docs).