Doctor command

commitbrief doctor

Health-check the pipeline without running an actual review. Useful in CI for "is my config still valid?" smoke tests and as a first-stop diagnostic when something stops working.

Synopsis

commitbrief doctor [-q|--quiet]

What it checks

The checks run in this order and produce one line per result. Each line is prefixed with a status glyph (✓ green / ⚠ yellow / ✗ red).

#	Check	Pass condition	Fail mode
1	git binary on PATH	exec.LookPath("git") succeeds	StatusFail
2	config schema valid	Merged config is non-nil and provider is set	StatusFail
3	COMMITBRIEF.md source	File present, or fall through to embedded default	StatusFail only on read error
4	OUTPUT.md template valid	Either embedded default or user template parses + executes	StatusFail on parse/template errors
5	at least one provider configured	Some provider has an API key (or Ollama is active with base_url)	StatusFail if none configured
6	active provider has credentials	config.provider itself has credentials (UC-03)	StatusFail if active provider is empty / unknown / keyless
7	cache directory writable	Create + delete a temp file under <repo>/.commitbrief/cache/	StatusFail on permission errors; StatusWarn on partial issues
8	.commitbrief/ in .gitignore	Repo .gitignore contains .commitbrief/, .commitbrief, or /.commitbrief/	StatusWarn (missing entry or missing file) / StatusFail (unreadable)

After the synchronous checks, doctor also runs a per-provider connection ping for every provider that looks configured (has an API key, or is the active ollama with a base_url). Pings are fanned out concurrently with a 5-second timeout each. A failing ping is StatusWarn (not Fail) — one broken provider out of three is recoverable.

Output

Doctor — running 9 checks

✓ git binary on PATH                       /usr/bin/git
✓ config schema valid
✓ COMMITBRIEF.md source                    /repo/COMMITBRIEF.md
✓ OUTPUT.md template valid                 built-in default
✓ at least one provider configured         anthropic
✓ active provider has credentials          anthropic
✓ cache directory writable                 /repo/.commitbrief/cache
⚠ .commitbrief/ in .gitignore              .commitbrief/ not listed; run 'commitbrief setup --local' to add it
✓ anthropic connection                     ok (412ms)

9 checks: 8 ok, 1 warning, 0 failed

Flags

Flag	Short	Notes
--quiet	-q	Print only warning and failed rows (suppress the heading and OK rows). The summary line still prints.

Exit codes

Code	Condition
0	Zero StatusFail rows. Warnings do not fail.
1	One or more StatusFail rows. Error message includes the count.

This makes doctor safe to wire into CI as a config-validity gate: warnings stay non-blocking while real misconfigurations break the build.

When to run

• After running commitbrief setup — verify the new config end-to-end.
• After changing providers — verify the new active provider has credentials (UC-03).
• As a CI step — fail the build on a broken config before any review fires.
• When troubleshooting any other command — narrows down which layer is broken.