CLI-Referenz

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

Jeder Befehl schreibt sein Ergebnis als JSON nach stdout und seine Logs nach stderr, sodass Piping genau so funktioniert, wie man es sich wünscht:

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

Globale Optionen

Globale Optionen stehen vor dem Unterbefehl:

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

Nur Phase 1: den statischen Aufrufgraph bauen. Kein LLM, kein Schlüssel, kostenlos.

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

--lang akzeptiert auto oder genau eines von: cpp csharp dart go java kotlin objc ocaml php python ruby rust scala shell solidity swift typescript zig. auto erkennt und verschmilzt jede Sprache in einem Durchgang und ist fast immer das, was man will.

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

files zählt, was tatsächlich gelesen und geparst wurde; filesUnparsed zählt, was nicht — und jede dieser Dateien steht mit einem Grund in scan-coverage.json. Siehe Artefakt-Formate.

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

generate

Die vollständige Pipeline. Braucht einen LLM-Endpunkt für alles nach phase 1.

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

Pipeline-Optionen

Durchsatz-Optionen

LLM-Optionen (geteilt von generate, plan, resync, studio)

Der API-Schlüssel ist nie ein Flag. Setze OPENAI_API_KEY (oder HANDBOOK_LLM_API_KEY) in der Umgebung oder in einer .env-Datei. In einer Konfigurationsdatei wird er abgelehnt, denn Konfigurationsdateien werden committet.

Der zusätzliche Anfrage-Body ist ebenfalls nie ein Flag und wird aus demselben Grund in einer Konfigurationsdatei abgelehnt. Setze OPENAI_EXTRA_BODY (oder HANDBOOK_LLM_EXTRA_BODY) in der Umgebung: Er mischt Hersteller-Felder in jeden Anfrage-Body — etwa {"thinking":{"type":"disabled"}} — und weil er frei formulierbar ist, lässt sich darin ein Tuning-Feld nicht von einem Auth-Feld unterscheiden. Modell-, Nachrichten- und Token-Felder lassen sich darüber nicht überschreiben.

--base-url ist ein Flag und in einer Konfigurationsdatei willkommen — ein Team, das jeden Checkout auf dasselbe gemeinsame Gateway richtet, ist genau das, wofür diese Datei da ist. Eine URL mit eingebetteten Zugangsdaten (https://user:pass@gw.internal/v1) wird dort abgelehnt, und nur dort; die Zugangsdaten gehören in die Umgebung.

--provider wählt das Wire-Format, nicht den Anbieter: openai (die Vorgabe) spricht mit jedem OpenAI-kompatiblen Endpunkt, und das sind die meisten; anthropic und gemini gibt es für die beiden, die es nicht sind.

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

render

Arbeitsverzeichnis → Markdown, und optional mehr. Kein LLM.

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

--out ist nur befehlsbezogen: seine Umgebungsvariable heißt HANDBOOK_RENDER_OUT und nicht flach HANDBOOK_OUT, weil --out bei plan und skill etwas anderes bedeutet.

skill

Gerendertes Handbuch → SKILL-Paket für Agenten. Kein LLM.

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

validate

Ein SKILL-Paket prüfen. Kein LLM. Endet bei Fehlschlag mit 2.

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

Prüft Struktur, den Frontmatter-Vertrag, die Konsistenz zwischen Index und Etappenseiten, das Schema von coverage.json und die Frische der Hashes. Fehler und Warnungen gehen nach stderr.

plan

Handbuch-geführte Änderungslokalisierung. Braucht einen LLM-Endpunkt. Nur lesend.

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

Dazu die geteilten LLM-Optionen.

Endet mit einem Wert ungleich null, wenn der Planer aufgegeben hat — er hat Werkzeugergebnisse erfunden, die Züge aufgebraucht oder ohne Verwertbares abgeschlossen — statt eine Entschuldigung zu schreiben, die ein Skript in apply einspeisen würde.

apply

Die EDIT-Blöcke eines Plans anwenden. Kein LLM. Endet mit 2, wenn etwas nicht gelandet ist.

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": []
}

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

rollback

Einen Quellbaum aus einer Patch-Sicherung wiederherstellen. Kein LLM.

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

Ohne --force wird eine Datei abgelehnt, deren aktueller Hash nicht zum Hash nach dem Patch passt — sie wiederherzustellen würde stillschweigend zerstören, was seitdem getan wurde.

resync

Ein Handbuch nach einer Codeänderung nachziehen.

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

Dazu die geteilten LLM-Optionen.

studio

Die lokale Weboberfläche. Läuft bis Ctrl-C.

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

Dazu die geteilten LLM-Optionen — Studio löst sie über dieselben Schichten auf wie jeder andere Befehl, sodass sowohl --model als auch ein llm:-Block in der Konfigurationsdatei seine Jobs erreichen.

config

Die aufgelöste Konfiguration ausgeben und woher jeder Wert stammt. Kein 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 bedeutet „das Werkzeug hat funktioniert, und die Antwort ist nein“. Skripte sollten ihn anders behandeln als 1.

Die pnpm-Abkürzungen

Aus einem Klon heraus bauen diese jeweils zuerst und reichen Flags direkt durch:

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