heddle doctor

heddle doctor is the canonical repository-health entry point. Without a subcommand it renders the snapshot — mode, current thread and state, in-progress operation, sync status, execution context, changes preview, workspace counters, overall health, and a recommended next step. --profile adds local timing for the diagnosis read path.

heddle doctor docs and heddle doctor schemas are drift-checkers, and both ship in every build including published release binaries. They are meant to run in CI on every push.

doctor docs parses every embedded heddle [] [flags] invocation in markdown files and checks each against the live CLI surface, catching verb renames, unknown flags and invalid enum values. --path scans specific files and is repeatable; --all walks every tracked .md file. It exits non-zero on any drift. Note the scope: markdown only. It cannot see commands embedded in source files, which is exactly how this docs site drifted — the equivalent guard here is cli-spec.test.ts.

doctor schemas drift-checks docs/json-schemas.md against the registered schemas, and also exits non-zero on drift.

Flags

--profile

Include local timing for the diagnosis read path.

Examples

Health snapshot, machine-readable

bash$ heddle doctor --output json

Validate markdown docs against the binary

bash$ heddle doctor docs --all

See also

• heddle status
• heddle verify
• heddle fsck

Subcommands

• doctor docs Diff-check markdown documentation against the actual CLI surface; exits non-zero on drift
• doctor schemas Drift-check docs/json-schemas.md against the registered schemas