Commands

The complete CLI surface as of zurdo v1.13.1. Every subcommand carries extensive built-in help — zurdo <subcommand> --help describes its modes, load-bearing exit codes, and examples — and zurdo help <topic> prints offline guide pages right in the terminal. A bare zurdo <prd> is sugar for zurdo run <prd>.

Subcommands

zurdo doctor — diagnose the environment

zurdo run won’t start and you want to know why, before writing a PRD or spending a token. zurdo doctor (v1.10.0) re-checks the environment half of the run pre-flight — with no PRD argument, without acquiring the run lock, and without writing anything to disk:

zurdo doctor                  # full diagnostic
zurdo doctor --skip-probes    # environment only — spawns no provider process at all
zurdo doctor --format json    # one parseable document for tooling

Output is a list of sections, each holding <status> <label>: <detail> rows with an optional hint: line:

The blocking/advisory split is what makes doctor safe as a CI gate: only fail rows move the exit code. A vocabulary gap, a stale lock, a missing .gitignore entry, an unbuilt Lumen index, and a stopped Vela daemon are all warn — reported, never gating.

The model probes reuse the stdout they already captured to run the vocabulary canary, so the canary costs zero extra process spawns. --skip-probes suppresses the spawn itself, not just the classification — neither the probes nor the canary’s --version lookup runs — which is what makes doctor safe offline, in CI, and on a metered account.

Exit 0 when everything passed or only advisories were reported; exit 2 when the config is missing or unloadable; exit 4 on any blocking finding — the same code the run pre-flight uses for a failed model check.

Machine-readable output

zurdo validate, zurdo verify, and zurdo state list accept --format json (v1.12.0), emitting one shared versioned envelope so a CI consumer parses one contract rather than three per-command shapes:

{ "schema_version": 1, "command": "validate", "data": { "ok": true, "errors": [], "warnings": [] } }

In JSON mode stdout is a single document and diagnostics stay on stderr; a parse or validation failure reports its errors in the payload rather than only as text. --format json changes rendering only — the exit code for a given input is identical to text mode on all three commands.

zurdo report and zurdo doctor have their own JSON shapes: report’s schema is load-bearing enough to be the default and evolves independently, and doctor --format json carries every section it renders.

zurdo validate --strict

--strict (v1.12.0) promotes four of the six warn-lint families — grep-target, vacuous-shell, grep-tautology, uncovered-requirement — to validation errors, so a PRD that would otherwise pass with warnings exits 2, the same code a structural error produces. Two families are exempt:

• skill-resolution — permanently. PRD-referenced skills are user-managed, so a CI checkout legitimately lacks them; promoting this family would fail every strict run for a non-defect.
• doc-echo — pending field data on its false-positive rate. It asserts a judgment about authorial intent, not a provable fact about the PRD.

It composes with --format json: a promoted finding moves from the warnings array to errors, and ok goes false. Without the flag every family stays advisory and a PRD with warnings still exits 0.

zurdo analyze — pre-flight analysis

zurdo analyze <prd> runs the full pre-flight analysis and never proceeds to execution. Three modes:

--static-only conflicts with --fix (the fix loop is LLM-driven). --max-iterations N caps the --fix refinement loop — same spelling as run’s flag, but here it means the refinement-loop cap, and 0 is a flag error under --fix.

zurdo heal — re-aim misaimed grep hints

A [grep:] hint can fail because the code is wrong — or because the hint is wrong. zurdo heal <prd> re-aims failed [grep:]/[no-grep:] payloads using the prior run’s failure history plus the live working tree as evidence (select → propose → verify → apply). It requires an existing .zurdo/<slug>/prd.json from a prior run (exit 3 if absent) and [roles.analyzer]. On a TTY it offers each verified heal in place (y/N); on non-TTY or with --no-prompt it writes verified heals to <prd>.proposed.md. It never executes tasks and never writes prd.json.

zurdo review — walk the evidence, sign off [manual] criteria

zurdo review <prd> opens a full-screen terminal UI over a prior run’s recorded state. Everything is read-only except one action: signing off [manual] criteria. Three surfaces:

• Task list — every task with its prd.json status; passed-pending-review tasks carry an explicit << awaiting manual sign-off marker.
• Evidence detail — one criterion at a time: its prose, each hint’s source text, the latest iteration’s pass/fail verdict with the provenance the runner captured (exit code, typed failure reason, a bounded stderr excerpt), and an explicit warning when a hint’s evidence changed since the run-start baseline.
• Baseline diff — the working tree’s diff against the persisted .zurdo/<slug>/baseline, recomputed live when the session opens: the changed-path list and the selected file’s hunks. Degrades to a notice when no baseline was captured or git diff fails.

Navigation: j/k (or arrow keys) to move, Enter to descend into a task’s evidence, d for the diff, t back to the task list, Esc up a level, q to quit.

Sign-off (s) is offered only on an unsigned [manual] criterion of a task in passed-pending-review — automated criteria, tasks in other statuses, and already-signed criteria expose no sign-off action, and the footer advertises the key only where it works. Each sign-off prompts for an optional one-line reviewer note, then an explicit confirmation naming the task; on confirm, a record (task id, criterion, note, UTC timestamp) is appended to .zurdo/<slug>/review-log.jsonl — a tamper-evident hash chain anchored at the run’s PRD hash. Signing a task’s last unsigned [manual] criterion additionally flips it passed-pending-review → passed in prd.json (the only prd.json write this surface ever makes; the run lock, held for the whole session, means no concurrent run can race it). Sign-offs are irrevocable — there is no unsign — and a broken log chain disables sign-off rather than appending to it. When the PRD hash changes (e.g. after --reset), the old log is archived and a fresh chain begins. Already-signed criteria render with their note and sign-off time on later sessions.

Guard rails, checked before any TUI setup: review requires an interactive terminal — non-TTY stdin or --no-prompt prints a one-line stderr pointer at zurdo report and exits 2. It requires an existing .zurdo/<slug>/prd.json from a prior run (exit 3 if absent) and refuses to start while another process holds the run lock (exit 3).

zurdo help — guide pages in the terminal

Bare zurdo help lists every subcommand and every guide topic. zurdo help <name> with a subcommand name renders that subcommand’s own --help; otherwise the name is looked up among the compiled-in guide topics:

hints · prd-grammar · exit-codes · config · workflow · state-dir

The topics are condensed, offline versions of this documentation — the hint-type menu, the PRD grammar rules, the exit-code table, the config key reference, the operating loop, and the .zurdo/<slug>/ layout. A subcommand name always shadows a topic of the same name; a name matching neither is an error on stderr, exit 2.

Shell completions and man pages

zurdo completions <shell> prints a completion script for bash, zsh, fish, elvish, or powershell to stdout, generated from the same command tree that parses every invocation — so it always matches the installed binary. Nothing is written to disk and no config or repo is touched; it works from any directory:

eval "$(zurdo completions zsh)"          # or:
zurdo completions bash > /etc/bash_completion.d/zurdo
zurdo completions fish | source

Installs via Homebrew get bash/zsh/fish completions and man pages automatically (man zurdo, man zurdo-run, …); release tarballs bundle both under completions/ and man/ — see Installation.

Flags by subcommand

zurdo run

The pre-v1.7.0 mode flags --analyze, --fix, --static-only, and --heal still parse as hidden deprecated aliases (see the callout above) but are no longer listed in --help.

zurdo validate

zurdo doctor

zurdo analyze

zurdo heal / zurdo review / zurdo verify / zurdo report / zurdo state list

zurdo init

zurdo skills install

Global flags

Apply across subcommands:

Examples

zurdo init                                  # bootstrap config + skills in this repo
zurdo doctor                                # why won't a run start? config, PATH, models, state
zurdo doctor --skip-probes --format json    # offline environment check, parseable
zurdo validate prds/feature.md              # free, instant grammar check
zurdo validate prds/feature.md --strict     # advisory lints become errors (CI gate)
zurdo analyze prds/feature.md --static-only # lint hints without an LLM
zurdo run prds/feature.md                   # the main event
zurdo run prds/feature.md --resume          # continue after Ctrl-C, no prompt
zurdo heal prds/feature.md                  # re-aim grep hints that failed last run
zurdo verify prds/feature.md                # re-check criteria after hand edits
zurdo review prds/feature.md                # walk the evidence, sign off [manual] criteria
zurdo report prds/feature.md --format md    # human-readable run report
zurdo reason match prds/feature.md          # preview lessons that would inform this PRD
zurdo help workflow                         # guide pages, offline in the terminal
eval "$(zurdo completions zsh)"             # shell completions from the live binary
zurdo skills install --all --all-providers  # every bundled skill, every provider

Exit codes

CI wrappers can branch cleanly on 5 (real failure) vs 6 (budget) vs 7/8 (analyze-fix didn’t converge) — see the CI integration example. The same table ships in the binary: zurdo help exit-codes.

Next: Configuration