heretic-cli doctor | VibeCoder Heretic

Synopsis

heretic-cli doctor [--fix]

Runs ten checks in a fixed order, one line each, then a summary. Statuses are [pass], [warn], [fail] and [skip] — only [fail] affects the exit code.

The ten checks

#	Check	Pass	Warn	Fail
1	Docker daemon	`Docker daemon is running`	—	`Docker daemon is not running` / `Failed to check Docker: …`
2	Docker version	`Docker version <v> (API <api>)` when the API is ≥ 1.41	—	API below 1.41, or `Failed to get Docker version: …`
3	Docker Compose	`Docker Compose is available`	`Docker Compose not available (optional for most operations)`	—
4	Config directory	`<~/.heretic> exists`; with `--fix`: `Created <dir>`	missing (`… does not exist (use --fix to create)`) or the creation failed	—
5	Settings file	`<~/.heretic/settings.yaml> is valid`	`… missing or invalid (will use defaults)`	—
6	Global profiles	`<n> profile(s) validated`	—	`Invalid profiles found: …` / `Failed to load profiles: …`
7	Local config	`<n> local config(s) valid: a, b`	—	`Local config validation failed: …`
8	Required images	`All required images are available`; with `--fix`: `Pulled <n> missing image(s)`	`Missing <n> image(s): … (use --fix to pull)` / `Some images failed to pull`	—
9	Network connectivity	`Docker Hub is reachable`	`Docker Hub returned status <n>` / `Unable to reach Docker Hub (may affect image pulls)`	—
10	Volume paths	`All volume source paths exist`	`Non-existent paths found: …`	—

Check 3 shells out to docker compose version, so it needs the docker CLI, not just the daemon socket. Check 9 treats HTTP 401 from the registry as success (it is the expected unauthenticated answer) with a 5 s timeout.

Check 7 skips with No local config in current directory when .heretic/cli/ holds no profile configs. Otherwise it resolves each local profile — which executes secret scripts — and validates the result, so a broken override shows up here, including the all-comments local-init template (Invalid config: expected an object).

Check 10 skips volume sources that still contain ${…} for global profiles, and checks the interpolated sources of local configs.

Summary and exit code

Summary: 6 passed, 1 warnings, 2 failed

The command exits 1 when at least one check failed, otherwise 0. Warnings never fail it — if you gate CI on doctor, grep for [warn] as well.

What `--fix` actually does

Exactly two things:

Creates ~/.heretic/ when check 4 finds it missing.
Pulls missing images referenced by global profiles (check 8), logging ✓ Pulled <image> or ✗ Failed to pull <image>: ….

It does not start Docker, install Compose, create settings.yaml, repair invalid profiles, fix local configs, create missing volume source directories, or change permissions.

Known limitation in 0.1.0

The global-profile checks report nothing

Checks 6, 8 and 10 iterate the profile collection incorrectly, so for global profiles they are vacuous:

check 6 always reports [pass] 0 profile(s) validated, even with many valid profiles, and can never report an invalid one
check 8 builds an empty image set, so it always reports All required images are available and --fix never pulls anything
check 10's global-profile loop never runs (its local-config loop still works)

Use these instead, they are exact:

heretic-cli agents validate               # real profile validation (exit 1 on error)
heretic-cli local-validate                # real local-config validation + resolved dump
heretic-cli agents show <name> --resolved  # confirm interpolation and volume paths
docker images                              # confirm the profile's image exists

Example run

$ heretic-cli doctor
[fail] Docker daemon is not running
[fail] Failed to get Docker version: Was there a typo in the url or port?
[pass] Docker Compose is available
[pass] /home/you/.heretic exists
[pass] /home/you/.heretic/settings.yaml is valid
[pass] 0 profile(s) validated
[skip] No local config in current directory
[warn] Failed to check images: …
[pass] Docker Hub is reachable
[pass] All volume source paths exist
Summary: 6 passed, 1 warnings, 2 failed

The Was there a typo in the url or port? wording comes from the Docker client library and simply means the daemon socket could not be reached.

Capturing a run for a bug report

All output goes through the logger, so --log-file captures a complete run:

heretic-cli --log-file ./doctor.log doctor
heretic-cli -V --log-file ./doctor-verbose.log doctor

doctor writes nothing to disk unless --fix is passed.

Next Steps

Troubleshooting — symptom-to-fix table
Validation — every validation rule and message
local-init — local-validate and the resolved dump