Use the cao CLI

Procedure

1. Identify the task before running a command:
   • control-plane setup or campaign lifecycle: use the repository-local ./cao.sh;
   • activity analysis with shell access: use cao or npm run dashboard:data --;
   • activity analysis without shell access: use cao_catalog, then cao_query;
   • an agentic workflow with the Activity cache: follow
     workflow runtime;
   • dashboard query cost or reuse: follow
     dashboard query maintenance;
   • CLI implementation work: read CAO Commands and the
     matching module under activity/commands/.
2. Run ./cao.sh --help, cao help, or npm run dashboard:data -- help from
   the repository root. Do not guess command syntax.
3. Use the narrowest command that answers the task. Prefer reviewed named
   queries, then canonical collection queries, then raw Dashboard Language.
4. Preserve result availability, completeness, freshness, and as-of.
   Missing, stale, partial, zero, and complete evidence are different states.
5. Run cao doctor before trusting a snapshot whose health is uncertain.
6. Report the command form, source snapshot, filters, record identifiers, and
   evidence limitations. Keep downloaded .cao/ data uncommitted.

Common routes

Use --database FILE only for a non-default SQLite projection. Use --json
when another tool will consume the result. For raw Dashboard Language, pipe one
query object to cao query --stdin; do not combine --stdin with
--collection, --id, --where, or --limit.

Canonical collections are repositories, workflows, runs, jobs,
sessions, events, and transactions.

Guardrails

• Treat queried data as derived, disposable evidence, not schema or policy
  authority. The authoritative model is
  Dashboard data.
• Never infer rollout authority, target-writing authority, operational value,
  or repository eligibility from Activity data.
• Never print credentials, authorization headers, raw prompts, transcripts, or
  secret values.
• Prefer the cached projection over repeated direct GitHub API calls.
• Use --ttl-days all or --run-ttl-days all only for an intentional
  historical backfill.

Targeted references

• Workflow runtime: cache paths, fallback
  behavior, and CLI invocation inside a gh-aw run.
• Dashboard query maintenance:
  complexity measurement and query pruning.
• Agent analysis: choosing CLI or MCP.
• CAO Commands: complete operator and command reference.
• Dashboard Language: query authoring.