CLI リファレンス

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

すべてのコマンドは 結果を JSON として stdout に、ログを stderr に 書き出すため、 パイプは期待どおりに動作します:

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

グローバルオプション

グローバルオプションはサブコマンドの 前 に置きます:

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 のみ: 静的なコールグラフを構築します。LLM 不要、キー不要、無料です。

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

--lang は auto、または次のいずれか 1 つを受け付けます: cpp csharp dart go java kotlin objc ocaml php python ruby rust scala shell solidity swift typescript zig。 auto は 1 回のパスですべての言語を検出してマージします。ほとんどの場合、これが求めているものです。

出力するファイル: phase1/graph.json、functions.csv、graph.dot、dropped-calls.json、 scan-coverage.json。

files は実際に読み取ってパースできたものの数、filesUnparsed はそうでなかったものの数で、 後者は 1 つ残らず理由付きで scan-coverage.json に名指しされます。 アーティファクト形式 を参照してください。

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

generate

パイプライン全体です。phase 1 より先へ進むには LLM エンドポイントが必要 です。

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

パイプラインオプション

スループットオプション

LLM オプション (generate、plan、resync、studio で共通)

API キーは 決してフラグにはなりません。環境または .env ファイルで OPENAI_API_KEY (または HANDBOOK_LLM_API_KEY) を設定してください。設定ファイルはコミットされるものなので、 設定ファイル内での指定は拒否されます。

追加のリクエストボディも 決してフラグにはなりません。同じ理由で、設定ファイル内での指定も 拒否されます。環境で OPENAI_EXTRA_BODY (または HANDBOOK_LLM_EXTRA_BODY) を設定してください。 これはベンダー固有のフィールドをすべてのリクエストボディにマージします — たとえば {"thinking":{"type":"disabled"}} です — が、中身が自由形式であるため、チューニング用のフィールドと認証用のフィールドを見分ける手段が ありません。model、message、token の各フィールドをこれで上書きすることはできません。

--base-url は フラグです。設定ファイルに書いても構いません — チームがすべてのチェックアウトを 1 つの共有ゲートウェイに向ける、というのはまさにあのファイルの用途そのものです。ただし認証情報を 埋め込んだ URL (https://user:pass@gw.internal/v1) だけは、そこで拒否されます。拒否されるのはそこ だけです。認証情報は環境に置いてください。

--provider が選ぶのはベンダーではなくワイヤフォーマットです: openai（デフォルト）は OpenAI 互換のあらゆるエンドポイント、つまりほとんどのものと話せます。anthropic と gemini は、そうでない 2 つのためにあります。

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

render

作業ディレクトリ → markdown、必要に応じてそれ以上のもの。LLM 不要です。

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

--out は スコープ付きのみ です: その環境変数はフラットな HANDBOOK_OUT ではなく HANDBOOK_RENDER_OUT です。--out は plan と skill では別の意味を持つためです。

skill

レンダリング済みの handbook → エージェント用 SKILL パッケージ。LLM 不要です。

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

validate

SKILL パッケージを検査します。LLM 不要。失敗時は 2 で終了します。

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

構造、フロントマターの契約、インデックス ↔ ステージページの整合性、coverage.json の スキーマ、ハッシュの鮮度を検査します。エラーと警告は stderr に出力されます。

plan

handbook に導かれた変更箇所の特定。LLM エンドポイントが必要です。読み取り専用です。

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

加えて、共通の LLM オプションが使えます。

プランナーが諦めた場合 — ツールの結果を捏造した、ターンを使い切った、使えるものが何も 残らなかった — は、スクリプトが apply に渡してしまうような謝罪文を書く代わりに、 ゼロ以外の終了コードで終了します。

apply

プランの EDIT ブロックを適用します。LLM 不要。1 つでも適用できなかった場合は 2 で終了します。

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

ステータス: applied · created · no-match · ambiguous · file-missing · not-a-file · unsafe-path · undecodable · skipped。

rollback

パッチのバックアップからソースツリーを復元します。LLM 不要です。

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

--force がない場合、現在のハッシュがパッチ適用後のハッシュと一致しないファイルは 拒否されます — 復元すれば、それ以降に行われた作業を黙って破壊してしまうからです。

resync

コードの変更後に handbook を前へ進めます。

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

加えて、共通の LLM オプションが使えます。

studio

ローカルの Web UI です。Ctrl-C を押すまで動き続けます。

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

加えて、共通の LLM オプションが使えます — Studio は他のすべてのコマンドと同じレイヤーから それらを解決するため、--model も設定ファイルの llm: ブロックも、そのジョブに届きます。

config

解決済みの設定と、各値がどこから来たのかを表示します。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

終了コード

2 は 「ツールは動作し、その答えが No だった」 という意味です。スクリプトは、これを 1 とは区別して扱うべきです。

pnpm のショートカット

クローンしたリポジトリからは、いずれもまずビルドを行い、フラグをそのまま転送します:

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