Referência da CLI

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

Todo comando escreve seu resultado no stdout como JSON e seus logs no stderr, então o encadeamento com pipes funciona exatamente como você esperaria:

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

Opções globais

As opções globais vêm antes do subcomando:

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

Somente a Phase 1: constrói o grafo de chamadas estático. Sem LLM, sem chave, de graça.

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

--lang aceita auto ou qualquer um destes: cpp csharp dart go java kotlin objc ocaml php python ruby rust scala shell solidity swift typescript zig. auto detecta e mescla todas as linguagens em uma única passagem e é quase sempre o que você quer.

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

files conta o que de fato foi lido e parseado; filesUnparsed conta o que não foi, e cada um desses está nomeado, com um motivo, em scan-coverage.json. Veja Formatos de artefato.

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

generate

O pipeline completo. Precisa de um endpoint de LLM para qualquer coisa além da Phase 1.

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

Opções de pipeline

Opções de vazão

Opções de LLM (compartilhadas por generate, plan, resync, studio)

A chave de API nunca é uma flag. Defina OPENAI_API_KEY (ou HANDBOOK_LLM_API_KEY) no ambiente ou em um arquivo .env. Ela é rejeitada em um arquivo de configuração, porque arquivos de configuração são commitados.

O corpo de requisição extra também nunca é uma flag, e é rejeitado em um arquivo de configuração pelo mesmo motivo. Defina OPENAI_EXTRA_BODY (ou HANDBOOK_LLM_EXTRA_BODY) no ambiente: ele mescla campos do fornecedor em todo corpo de requisição — {"thinking":{"type":"disabled"}}, por exemplo — e, por ser de formato livre, não há como distinguir ali dentro um campo de ajuste de um campo de autenticação. Campos de modelo, mensagem e tokens não podem ser sobrescritos por ele.

--base-url é uma flag, e é bem-vinda em um arquivo de configuração — um time apontando todos os seus checkouts para um mesmo gateway compartilhado é exatamente para isso que esse arquivo serve. Uma URL que embute credenciais (https://user:pass@gw.internal/v1) é recusada ali, e só ali; deixe a credencial no ambiente.

--provider escolhe o formato do protocolo, não o fornecedor: openai (o padrão) fala com qualquer endpoint compatível com OpenAI, que é a maioria; anthropic e gemini existem para os dois que não são.

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

render

Diretório de trabalho → markdown, e opcionalmente mais. Sem LLM.

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

--out é apenas escopada: sua variável de ambiente é HANDBOOK_RENDER_OUT, não uma HANDBOOK_OUT plana, porque --out significa coisas diferentes em plan e skill.

skill

Handbooks renderizado → pacote SKILL para agentes. Sem LLM.

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

validate

Verifica um pacote SKILL. Sem LLM. Sai com 2 em caso de falha.

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

Verifica a estrutura, o contrato do frontmatter, a consistência entre índice ↔ páginas de etapa, o schema do coverage.json e a atualidade dos hashes. Erros e avisos vão para o stderr.

plan

Localização de mudanças guiada pelo handbook. Precisa de um endpoint de LLM. Somente leitura.

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

Mais as opções de LLM compartilhadas.

Sai com código diferente de zero se o planejador desistiu — inventou resultados de ferramentas, esgotou os turnos ou terminou sem nada aproveitável — em vez de escrever um pedido de desculpas que um script alimentaria no apply.

apply

Aplica os blocos EDIT de um plano. Sem LLM. Sai com 2 se algo não foi aplicado.

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: applied · created · no-match · ambiguous · file-missing · not-a-file · unsafe-path · undecodable · skipped.

rollback

Restaura uma árvore de código a partir de um backup de patch. Sem LLM.

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

Sem --force, um arquivo cujo hash atual não bate com o hash pós-patch é recusado — restaurá-lo destruiria silenciosamente tudo o que foi feito desde então.

resync

Avança um handbook depois de uma mudança de código.

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

Mais as opções de LLM compartilhadas.

studio

A interface web local. Roda até Ctrl-C.

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

Mais as opções de LLM compartilhadas — o Studio as resolve a partir das mesmas camadas que todos os outros comandos, então tanto --model quanto um bloco llm: em arquivo de configuração chegam aos seus jobs.

config

Imprime a configuração resolvida e de onde veio cada valor. Sem 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

Códigos de saída

2 significa "a ferramenta funcionou, e a resposta é não". Scripts devem tratá-lo de forma diferente de 1.

Os atalhos do pnpm

A partir de um clone, cada um destes faz o build antes e repassa as flags diretamente:

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