CLI reference

handbook [global options] <command> [command options]

Every command writes its result to stdout as JSON and its logs to stderr, so piping works exactly as you would hope:

handbook analyze --source ~/code/api --work work/api | jq .functions

Global options

Global options go before the subcommand:

handbook --env prod -v generate --source ~/code/api --work work/api

$ handbook --env-file /gone.env config
node: /gone.env: not found        # node, exit 9, before Handbooks ever runs

$ HANDBOOK_ENV_FILE=/gone.env handbook config
handbook: error: ENOENT: no such file or directory, open '/gone.env'

analyze

Phase 1 only: build the static call graph. No LLM, no key, free.

handbook analyze --source <dir> --work <dir> [--lang <lang>]

--lang accepts auto or any one of: cpp csharp dart go java kotlin objc ocaml php python ruby rust scala shell solidity swift typescript zig. auto detects and merges every language in one pass and is almost always what you want.

Writes phase1/graph.json, functions.csv, graph.dot, dropped-calls.json, scan-coverage.json.

files counts what was actually read and parsed; filesUnparsed counts what was not, and every one of those is named with a reason in scan-coverage.json. See Artifact formats.

{
  "language": "multi",
  "files": 412,
  "functions": 3187,
  "edgesKept": 9042,
  "edgesDropped": 611,
  "filesUnparsed": 3
}

generate

The full pipeline. Needs an LLM endpoint for anything past phase 1.

handbook generate --source <dir> --work <dir> [options]

Pipeline options

Throughput options

LLM options (shared by generate, plan, resync, studio)

The API key is never a flag. Set OPENAI_API_KEY (or HANDBOOK_LLM_API_KEY) in the environment or a .env file. It is rejected in a config file, because config files get committed.

The extra request body is never a flag either, and is rejected in a config file for the same reason. Set OPENAI_EXTRA_BODY (or HANDBOOK_LLM_EXTRA_BODY) in the environment: it merges vendor fields into every request body — {"thinking":{"type":"disabled"}}, for instance — and because it is free-form, there is no way to tell a tuning field from an auth field inside it. Model, message and token fields cannot be overridden through it.

--base-url is a flag and is welcome in a config file — a team pointing every checkout at one shared gateway is exactly what that file is for. A URL that embeds credentials (https://user:pass@gw.internal/v1) is refused there, and only there; keep the credential in the environment.

--provider selects the wire format, not the vendor: openai (the default) speaks to every OpenAI-compatible endpoint, which is most of them; anthropic and gemini are there for the two that are not.

{
  "phasesRun": ["1", "2a", "2b", "2c", "3"],
  "nCards": 412,
  "nStages": 9,
  "nUnassignedFiles": 0,
  "nRegisters": 6,
  "usage": { "promptTokens": 1840221, "completionTokens": 214880, "totalTokens": 2055101 }
}

render

Work dir → markdown, and optionally more. No LLM.

handbook render --work <dir> [--title <t>] [--html] [--html-single] [--agent-site] [--llms-txt]

--out is scoped only: its environment variable is HANDBOOK_RENDER_OUT, not a flat HANDBOOK_OUT, because --out means something different on plan and skill.

skill

Rendered handbook → agent SKILL package. No LLM.

handbook skill --handbook <dir> --out <dir> --name <slug> [options]

validate

Check a SKILL package. No LLM. Exits 2 on failure.

handbook validate --skill <dir> [--source <dir>]

Checks structure, the frontmatter contract, index ↔ stage-page consistency, coverage.json schema, and hash freshness. Errors and warnings go to stderr.

plan

Handbooks-guided change localization. Needs an LLM endpoint. Read-only.

handbook plan --source <dir> --request "<text>" [--handbook <dir>] [--out <file>]

Plus the shared LLM options.

Exits non-zero if the planner gave up — it invented tool results, ran out of turns, or finished with nothing usable — rather than writing an apology that a script would feed into apply.

apply

Apply a plan's EDIT blocks. No LLM. Exits 2 if anything did not land.

handbook apply --source <dir> --plan <file> [--dry-run] [--backup-root <dir>]

{
  "ok": true,
  "dryRun": false,
  "outcomes": [
    { "index": 1, "file": "src/upload.py", "where": "Uploader.send (~88)", "status": "applied", "line": 88 }
  ],
  "changedFiles": ["src/upload.py"],
  "backupDir": "/repo/.handbook-patches/2026-08-08T14-05-11-204Z",
  "problems": []
}

Statuses: applied · created · no-match · ambiguous · file-missing · not-a-file · unsafe-path · undecodable · skipped.

rollback

Restore a source tree from a patch backup. No LLM.

handbook rollback --backup <dir> [--source <dir>] [--force]

Without --force, a file whose current hash does not match the post-patch hash is refused — restoring it would silently destroy whatever was done since.

resync

Roll a handbook forward after a code change.

handbook resync --case <dir> --work <dir> [options]

Plus the shared LLM options.

studio

The local web UI. Runs until Ctrl-C.

handbook studio [--port <n>] [--host <addr>] [--state-dir <dir>]

Plus the shared LLM options — Studio resolves them from the same layers as every other command, so --model and a config-file llm: block both reach its jobs.

config

Print the resolved configuration and where every value came from. No LLM.

handbook config [--command <name>] [--json] [--check]

handbook config --command generate      # a table, with provenance per row
handbook config --json | jq '.settings[] | select(.source.kind == "env")'
handbook config --check                 # put this one in CI

Exit codes

2 means "the tool worked, and the answer is no". Scripts should treat it differently from 1.

The pnpm shortcuts

From a clone, each of these builds first and forwards flags straight through:

pnpm analyze  --source ~/code/proj --work work/proj
pnpm generate --source ~/code/proj --work work/proj
pnpm render   --work work/proj --html --agent-site --llms-txt
pnpm skill    --handbook work/proj/handbook --out skills/proj --name proj
pnpm validate --skill skills/proj --source ~/code/proj
pnpm plan     --source ~/code/proj --request "…" --out plan.md
pnpm apply    --source ~/code/proj --plan plan.md --dry-run
pnpm rollback --backup ~/code/proj/.handbook-patches/<stamp>
pnpm resync   --case cases/mycase --work work/proj
pnpm studio
pnpm config:show --command generate
pnpm handbook --help