CLI Automation Patterns

CLI Automation Patterns

The ccam CLI is useful for terminal investigations, repeatable checks, and narrow automation. Prefer its documented commands over querying SQLite directly because the CLI preserves normalization, auth, and compatibility behavior.

Interactive operations

npx ccam repl

Inside the REPL, help, commands, and watch 5 kanban provide a compact operations console. Each command runs in isolation, so a failed or interrupted command does not terminate the shell.

Health and situational awareness

npx ccam health
npx ccam stats
npx ccam kanban
npx ccam tail --session <session-id>

Use tail for live activity and stop it with Ctrl+C. For scheduled checks, prefer bounded list/stat commands that exit cleanly.

Investigation pattern

npx ccam sessions --status active --limit 25
npx ccam session <session-id>
npx ccam agents --session <session-id>
npx ccam events --session <session-id> --limit 100
npx ccam transcript <session-id>

Start broad, capture a stable identifier, then narrow. Avoid parsing decorative table output when the current command offers a machine-readable mode; check --help for the installed version.

Offline mode

When the server is down, supported read-only commands automatically read data/dashboard.db as a safe SQLite reader. Output is explicitly marked offline and may correct dead active sessions for display when the local process probe can answer. Offline mode does not mutate the database and does not provide live ingestion.

Do not build automation that silently treats offline data as current. Detect the warning or require ccam health first when freshness matters.

Mutation safety

Write commands require explicit acknowledgement such as --yes; destructive commands add specific confirmation values. Keep these out of unattended scripts unless the target and backup are independently validated. Prefer the sequence: list → select exact ID → dry/read check → mutate → verify.

Authentication

For a protected remote dashboard, provide the dashboard URL and credential through the supported environment/file configuration. Use a restricted secret file and never embed tokens in scripts, arguments recorded by process listings, or CI logs.

Full command catalog: CLI reference.