heddle doctor

heddle doctor is the canonical repository-health entry point. Without a subcommand it renders the structured snapshot — mode (hybrid vs standalone), current thread + state, in-progress operation, sync status, Git-overlay import hint, execution context, changes preview, workspace counters, overall health, and a recommended next step. JSON output is available via the global --json mode.

heddle doctor docs and heddle doctor schemas are drift-checkers for project maintainers — they're only present in non-release builds. The published release binaries ship without them, so a cargo install heddle-cli won't see these subcommands. Contributors building from source get them automatically, and a --features devtools flag is planned for opting back in on release builds for CI use.

When present, heddle doctor docs parses every embedded heddle [] [flags] invocation in markdown files and checks each one against the live CLI surface — catches verb renames, unknown flags, invalid enum values for --workspace/--scope/--kind/--output. Pass specific files via --path (repeatable), or --all to walk every tracked .md file. Exits non-zero on any drift.

When present, heddle doctor schemas validates docs/json-schemas.md samples against the canonical JSON schema registry; flags top-level key drift (renames, deletions, fields that leaked into samples but aren't in the schema). Also exits non-zero on drift. Wire both into CI on every push.

Flags

--profile

When `doctor` is invoked without a subcommand, include local timing for the health-read path.

--path <PATH>

For `doctor docs`: scan a specific markdown file. Repeatable.

--all

For `doctor docs`: walk every tracked `.md` file in the repo. The default when neither `--path` nor `--all` is given.

Examples

Validate docs are in sync with the binary

bash$ heddle doctor docs --alldoctor docs: no drift found across 28 file(s)

Validate JSON schema samples

bash$ heddle doctor schemasheddle doctor schemas — 47 verb(s) registered, doc: docs/json-schemas.md  ok   status: sample matches generated schema  ok   log: sample matches generated schemaNo drift detected.

See also

• heddle fsck

Subcommands

• doctor docs Diff-check markdown docs against the real CLI surface — exits non-zero on drift
• doctor schemas Diff-check `docs/json-schemas.md` against the canonical schema registry