Skip to content
Apothem
CLI reference

doctor

CLI reference for the apothem doctor command.

Check the health of what is installed. Where apothem verify checks the harnesses you select, doctor checks every installed harness and the shared profile in one pass.

Synopsis

apothem doctor [--project PATH] [--quiet|-q] [--verbose|-v]
               [--format plain|json] [--json] [--no-color]

What it checks

  • Shared profile. A present profile is validated against the packaged schema; a malformed one fails with its diagnostic code. A missing profile is reported, not failed (install creates one).
  • Installed harnesses only. A harness that is not installed is reported as not_installed and is not a failure, so a machine with one healthy harness passes. Project-scope harnesses are checked when --project names their root; without it they are reported as needs_project.
  • Verify. Each installed harness must pass the same check as verify.
  • Hook runtime. For each verified harness, doctor reads the files its latest install wrote, finds the hook commands Apothem registered there, and starts each interpreter and hook script once with a no-op payload (the registered arguments plus --help, {} on stdin, a scratch working directory, and PYTHONPATH removed). Nothing is written. A missing interpreter, a missing script, or a crash at import time fails the check.

Every failed check names a fix. Exits 0 when no check fails and 1 otherwise.

JSON output

--json keeps the earlier fields (version, python, platform, profile_path, profile_exists, profile_valid, harnesses, all_ok, and profile_error when the profile is invalid) and adds:

  • profile_error_code — the profile diagnostic code, when the profile is invalid.
  • project — the resolved --project root, or null.
  • harnesses[].status — ok, not_installed, needs_project, verify_failed, hook_failed, or error; plus verified and hooks ({"probed": N, "failed": [...]}, or null when no install record exists).
  • checks — one record per check: code (for example harness.verify_failed, hook.start_failed, ledger.unreadable, or a profile.* code), status (pass, fail, or info), harness, message, and fix.
{
  "schema_version": 1,
  "all_ok": false,
  "checks": [
    {
      "code": "hook.start_failed",
      "status": "fail",
      "harness": "claude-code",
      "message": "claude-code: a registered hook command cannot start: …",
      "fix": "Check that the interpreter in the hook command exists and runs, then …"
    }
  ]
}

Options

OptionDescription
--project PATHProject root for project-scope harnesses; without it they are reported as needs_project.
--quiet, -qSuppress informational output; only errors are emitted.
--verbose, -vAccepted for consistency with other commands; this command prints no extra output.
--format plain|jsonOutput format (default: plain).
--jsonShorthand for --format json.
--no-colorDisable ANSI color codes in output.
-h, --helpShow help and exit.

Examples

apothem doctor
apothem doctor --project .
apothem doctor --json

The default plain format prints human-readable diagnostics; --json (equivalent to --format json) emits a machine-readable document on stdout, suitable for piping into other tooling.

Exit codes

CodeMeaning
0All checks passed (also when no harness is installed yet)
1An installed harness does not verify, a registered hook command cannot start, an adapter could not be loaded or probed, or a present profile failed schema validation
64Usage error: an unknown option or command, or a missing or invalid option value. Under --json the error is a JSON envelope with code cli.usage.

See also

diff

CLI reference for the apothem diff command.

harnesses

CLI reference for the apothem harnesses command group.

On this page

SynopsisWhat it checksJSON outputOptionsExamplesExit codesSee also