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. Pass --output json for the machine-readable form.

heddle doctor docs and heddle doctor schemas are drift-checkers that ship in every build, including published release binaries, so cargo install heddle-cli gets them. They're meant to run in CI on every push.

heddle doctor docs parses every embedded heddle [] [flags] invocation in markdown files and checks each one against the live CLI surface. It 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.

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