Referencia de la CLI

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

Cada comando escribe su resultado en stdout como JSON y sus logs en stderr, así que las tuberías funcionan exactamente como esperarías:

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

Opciones globales

Las opciones globales van antes del 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

Solo Phase 1: construye el grafo de llamadas estático. Sin LLM, sin clave, gratis.

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

--lang acepta auto o cualquiera de: cpp csharp dart go java kotlin objc ocaml php python ruby rust scala shell solidity swift typescript zig. auto detecta y fusiona todos los lenguajes en una sola pasada y es casi siempre lo que quieres.

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

files cuenta lo que realmente se leyó y parseó; filesUnparsed cuenta lo que no, y cada uno de esos archivos aparece nombrado con su motivo en scan-coverage.json. Consulta Formatos de los artefactos.

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

generate

El pipeline completo. Necesita un endpoint LLM para cualquier cosa más allá de la Phase 1.

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

Opciones del pipeline

Opciones de rendimiento

Opciones de LLM (compartidas por generate, plan, resync, studio)

La clave de API nunca es un flag. Define OPENAI_API_KEY (o HANDBOOK_LLM_API_KEY) en el entorno o en un archivo .env. Se rechaza en un archivo de configuración, porque los archivos de configuración acaban commiteados.

El cuerpo extra de la petición tampoco es un flag, y se rechaza en un archivo de configuración por el mismo motivo. Define OPENAI_EXTRA_BODY (o HANDBOOK_LLM_EXTRA_BODY) en el entorno: fusiona campos del proveedor en el cuerpo de cada petición — {"thinking":{"type":"disabled"}}, por ejemplo — y, al ser de formato libre, no hay manera de distinguir dentro de él un campo de ajuste de uno de autenticación. Los campos de modelo, mensajes y tokens no se pueden sobrescribir por esa vía.

--base-url sí es un flag, y es bienvenido en un archivo de configuración: que un equipo apunte todos sus checkouts a un mismo gateway compartido es exactamente para lo que sirve ese archivo. Una URL que lleve credenciales incrustadas (https://user:pass@gw.internal/v1) se rechaza ahí, y solo ahí; deja la credencial en el entorno.

--provider elige el formato del protocolo, no el proveedor: openai (el valor por defecto) habla con cualquier endpoint compatible con OpenAI, que son casi todos; anthropic y gemini están para los dos que no lo son.

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

render

Directorio de trabajo → markdown, y opcionalmente más. Sin LLM.

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

--out tiene ámbito exclusivo: su variable de entorno es HANDBOOK_RENDER_OUT, no un HANDBOOK_OUT plano, porque --out significa algo distinto en plan y en skill.

skill

Handbooks renderizado → paquete SKILL para agentes. Sin LLM.

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

validate

Comprueba un paquete SKILL. Sin LLM. Sale con 2 si falla.

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

Comprueba la estructura, el contrato del frontmatter, la consistencia entre el índice ↔ las páginas de etapa, el esquema de coverage.json y la frescura de los hashes. Los errores y las advertencias van a stderr.

plan

Localización de cambios guiada por el handbook. Necesita un endpoint LLM. Solo lectura.

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

Más las opciones de LLM compartidas.

Sale con un código distinto de cero si el planificador se rindió — inventó resultados de herramientas, se quedó sin turnos o terminó sin nada aprovechable — en lugar de escribir una disculpa que un script acabaría pasándole a apply.

apply

Aplica los bloques EDIT de un plan. Sin LLM. Sale con 2 si algo no se aplicó.

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

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

rollback

Restaura un árbol de código desde una copia de seguridad de parches. Sin LLM.

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

Sin --force, un archivo cuyo hash actual no coincide con el hash posterior al parche se rechaza — restaurarlo destruiría silenciosamente todo lo hecho desde entonces.

resync

Adelanta un handbook después de un cambio de código.

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

Más las opciones de LLM compartidas.

studio

La interfaz web local. Se ejecuta hasta Ctrl-C.

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

Más las opciones de LLM compartidas — Studio las resuelve desde las mismas capas que cualquier otro comando, así que tanto --model como un bloque llm: de un archivo de configuración llegan a sus jobs.

config

Imprime la configuración resuelta y de dónde vino cada valor. Sin 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 salida

2 significa "la herramienta funcionó, y la respuesta es no". Los scripts deberían tratarlo de forma distinta a 1.

Los atajos de pnpm

Desde un clon, cada uno de estos compila primero y reenvía los flags tal cual:

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