doctor

cctally doctor

Read-only diagnostic. Answers the question: "why is my cctally data stale or broken?" by running every passive check across install, hooks, OAuth, database, data freshness, pricing coverage, and safety config, then emitting a severity-ranked report.

Modes

Mode	What it does
cctally doctor	Human-readable report
cctally doctor --json	Machine-readable JSON to stdout
cctally doctor --quiet / -q	Human mode; hide OK rows
cctally doctor --verbose / -v	Human mode; include per-check details blocks

--quiet and --verbose are mutually exclusive.

Exit codes

Code	Meaning
0	All checks are OK or WARN
2	Any check is FAIL

Loose mapping (WARN doesn't cause non-zero) makes cctally doctor usable as a healthcheck without false-positive noise: cctally doctor || alert-me.

Severity model

Level	Meaning
OK	Healthy. No user action needed.
WARN	Degraded but functional. Data still flowing; user may want to act.
FAIL	Broken. Data is wrong, or a critical workflow won't work.

Check inventory

Ten categories. Each check has a stable id (used as the JSON key), a one-line summary, and a remediation hint shown when severity != OK.

Install

• install.symlinks — WARN when any cctally-* command is unavailable. Reports "N/M available", counting available = ok + stale. PATH-aware: a command is counted available when its ~/.local/bin/ symlink is present, or when the command is reachable on $PATH via another install channel (e.g. a Homebrew <prefix>/bin/ install), so it no longer false-warns purely because ~/.local/bin/ lacks the link. A leftover link to an old Homebrew keg (<prefix>/Cellar/cctally/) or the npm shim, whose command is still reachable elsewhere, is reported as a cleanable stale state (counted available, listed in the new --json details.stale array) rather than a generic failure — the summary appends "N stale link(s) to clean" and the remediation is Run cctally setup to clean stale links. A wrong-target / dangling / non-symlink slot still counts as missing (wrong). One pinned-only-path case is special-cased: when cctally is reachable only through a legacy ~/.local/bin/ link to a keg (so cctally setup deliberately won't remove the only working copy), the remediation switches to a PATH-fix hint ("Put <prefix>/bin on your PATH (e.g. eval "$(brew shellenv)"), then run cctally setup to remove the legacy link"). The --json details keys present / total / missing are unchanged (missing spans wrong + missing); details.stale is additive.
• install.path — availability-aware: OK whenever cctally is reachable on $PATH via any channel (Homebrew <prefix>/bin/, an npm prefix, or source ~/.local/bin), summary cctally reachable on $PATH. WARN (cctally not reachable on $PATH) only when no channel makes it reachable; the remediation is channel-aware — a Homebrew keg is pointed at eval "$(brew shellenv)" (it owns no ~/.local/bin symlinks per the #119 policy), while source / npm installs get the export PATH="$HOME/.local/bin:$PATH" + cctally setup fix.
• install.update_channel — reports the configured update (release) channel cctally update tracks (stable | beta), distinct from the preview channel (prod|preview) in install.mode. OK for stable, or beta on npm/source. WARN on the beta+brew mismatch — Homebrew tracks the stable channel only (a beta opt-in silently resolves stable); the remediation points at npm/source or cctally config set update.channel stable. Never FAIL, so it doesn't affect the exit code.
• install.legacy_snippet — WARN when an old status-line snippet is detected.
• install.legacy_bespoke_hooks — WARN when the legacy hand-installed hooks are present.