Справочник CLI

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

Каждая команда пишет результат в stdout в виде JSON, а логи — в 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 или одно из: cpp csharp dart go java kotlin objc ocaml php python ruby rust scala shell solidity swift typescript zig. auto определяет и объединяет все языки за один проход и почти всегда является тем, что вам нужно.

Записывает phase1/graph.json, functions.csv, graph.dot, dropped-calls.json, scan-coverage.json.

files считает то, что действительно прочитано и разобрано; filesUnparsed — то, что нет, и каждый такой файл поимённо назван с причиной в scan-coverage.json. См. Форматы артефактов.

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

generate

Полный pipeline. Нужна конечная точка LLM для всего, что идёт после phase 1.

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

Опции конвейера

Опции пропускной способности

Опции LLM (общие для generate, plan, resync, studio)

Ключ API никогда не является флагом. Задайте OPENAI_API_KEY (или HANDBOOK_LLM_API_KEY) в окружении или в файле .env. В файле конфигурации он отклоняется, потому что файлы конфигурации попадают в коммиты.

Дополнительное тело запроса тоже никогда не является флагом и по той же причине отклоняется в файле конфигурации. Задавайте его через OPENAI_EXTRA_BODY (или HANDBOOK_LLM_EXTRA_BODY) в окружении: оно подмешивает вендорские поля в тело каждого запроса — например, {"thinking":{"type":"disabled"}}, — а форма у него произвольная, так что отличить в нём поле тонкой настройки от поля аутентификации невозможно. Поля модели, сообщений и токенов переопределить через него нельзя.

--base-url, наоборот, флагом остаётся, и в файле конфигурации ему самое место: один общий шлюз, на который вся команда направляет каждый свой клон, — это ровно тот случай, ради которого такой файл и нужен. Там — и только там — отклоняется URL со встроенными учётными данными (https://user:pass@gw.internal/v1); держите их в окружении.

--provider выбирает формат протокола, а не поставщика: openai (по умолчанию) работает с любым OpenAI-совместимым эндпоинтом, а таких большинство; anthropic и gemini — для двух оставшихся.

{
  "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_RENDER_OUT, а не плоская HANDBOOK_OUT, потому что --out означает разное в plan и skill.

skill

Отрендеренное руководство → 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

Локализация изменений с опорой на руководство. Нужна конечная точка LLM. Только чтение.

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

Плюс общие опции LLM.

Завершается с ненулевым кодом, если планировщик сдался — выдумал результаты инструментов, исчерпал ходы или закончил ничем пригодным — вместо того чтобы записать извинение, которое скрипт скормит в apply.

apply

Применить EDIT-блоки плана. Без LLM. Возвращает 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 resync --case <dir> --work <dir> [options]

Плюс общие опции LLM.

studio

Локальный веб-интерфейс. Работает до 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 означает «инструмент отработал, и ответ — нет». Скрипты должны обрабатывать его иначе, чем 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