---
title: heretic-cli doctor
description: "Environment health checks — all ten checks with their exact pass, warn, fail and skip messages, what --fix actually repairs, exit codes, and the known limitation of the global-profile checks"
canonical: https://giglabo.com/heretic/docs/heretic-cli/commands/doctor
locale: en
---

# heretic-cli doctor

> Markdown twin of https://giglabo.com/heretic/docs/heretic-cli/commands/doctor
> Site structure and the full page list for agents: https://giglabo.com/llms.txt

Environment health checks — all ten checks with their exact pass, warn, fail and skip messages, what --fix actually repairs, exit codes, and the known limitation of the global-profile checks

## 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:

1. **Creates `~/.heretic/`** when check 4 finds it missing.
2. **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

> **Warning: 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:
>
> ```bash
> 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:

```bash
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](https://giglabo.com/heretic/docs/heretic-cli/reference/troubleshooting) — symptom-to-fix table
- [Validation](https://giglabo.com/heretic/docs/heretic-cli/reference/validation) — every validation rule and message
- [local-init](https://giglabo.com/heretic/docs/heretic-cli/commands/local-init) — `local-validate` and the resolved dump

## Related

- HTML version of this page: https://giglabo.com/heretic/docs/heretic-cli/commands/doctor
- Site map for agents: https://giglabo.com/llms.txt