Resumen de la CLI

La autoridad es tu propia máquina: tldrx --help, y tldrx <command> --help para ver las banderas de un comando, sus valores permitidos, ejemplos y códigos de salida. Esta página es un mapa de la superficie, no una copia de ella.

Esta página es un recorrido curado: los comandos que de verdad vas a usar, agrupados por lo que estás intentando hacer. Nombra algunas banderas y otras no, a propósito.

Para todas las banderas — incluidas las que esta página deja fuera — mira Todos los comandos y flags. Esa página se genera al compilar desde src/cli/helpText.ts, el mismo registro que imprime --help y del que el guardián de argv rechaza banderas desconocidas, así que lista todos los comandos con todas sus banderas, todos los valores permitidos, todos los códigos de salida y las variables de entorno, y no puede quedarse atrás del código.

Los cinco que de verdad vas a escribir

tldrx init                  # detecta el workspace, mapea el código, pregunta solo los huecos
tldrx run new <slug> --scope feature --budget 25
tldrx next                  # corre la siguiente etapa; se detiene en una compuerta
tldrx answer Q1 "…"         # contesta lo que preguntó
tldrx approve --note "…"    # firma la compuerta; antes se vuelven a correr las verificaciones

Poner todo en marcha

Comando	Qué hace
tldrx doctor	Revisa el entorno local. Es la autoridad sobre lo que hace falta.
tldrx init	Detecta repos, arma el mapa de código, escribe .tldrx/, lista los huecos. Corre una vez tus comandos de build/test para comprobarlos; --no-probe lo salta.
tldrx interview --init	Contesta las preguntas de configuración en la terminal.
tldrx install --claude	Escribe la skill /tldrx, los hooks y la status line dentro de .claude/.
tldrx learn	El tutorial jugable en sandbox. Sin llave, sin red, $0.00.
tldrx update	npm i -g tldr-experts@latest, más el CHANGELOG entre la versión que tenías y la que quedó. Además, cualquier comando te avisa en una línea cuando ya hay una más nueva: fuera del camino caliente, cacheada, muda si falla la red, y nunca en --json ni dentro de un hook. TLDRX_UPDATE_CHECK=off lo apaga en una terminal; update_check: off en ~/.tldrx/config.yml, en toda la máquina.
tldrx status	Todo lo que en este workspace espera a una persona, y el comando para cada cosa.

Manejar un run

Comando	Qué hace
tldrx run new <slug>	Abre una pieza de trabajo. --scope, --budget, --seed, --gates, --attended-by host.
tldrx run status [<run>]	Dónde va, qué está esperando, cuánto costó. --json.
tldrx next [<run>]	Corre la siguiente etapa. --dry-run, --prepare/--commit, --review, --check, --effort, --max-reads.
tldrx run auto [<run>]	Llama a next una y otra vez hasta que algo te necesite. --max-usd, --until, --parallel, y --notify-every / --wait-answers / --wait-gates para correrlo del todo desatendido — ver Operar un run desatendido.
tldrx run attend host | --none	Entrega el run a una sesión host, o recupéralo.
tldrx run estimate	El único comando que adivina. Lo dice: ESTIMATE.
tldrx run unlock / run cancel	Limpia un lock viejo; cierra un run para siempre.

Decidir

Comando	Qué hace
tldrx approve	Firma la compuerta. --note, --as-agent, --evidence.
tldrx reject --note "…"	Regresa la etapa; --stage <phase>/<stage> revoca una firma ya dada.
tldrx gate template	Escribe el esqueleto de la nota de evidencia sobre la que firma una compuerta agent.
tldrx run gates set <stage>:<policy> --note "…"	La única manera sancionada de cambiar la política de compuertas después de run new.
tldrx questions cards	Las preguntas ABIERTAS del run como tarjetas de decisión imprimibles: contexto, lo que los documentos ya deciden, las opciones. Solo lee.
tldrx questions lint	Nombra cada bloque de pregunta que el parser no alcanza a ver: un ## Qn · Title mal escrito se lee como ausente, así que todo lo que viene después reporta "0 preguntas abiertas" y una compuerta auto firma encima. --fix los reescribe a la gramática sin cambiarles una palabra.
tldrx answer <Qid> "…"	Registra una respuesta como hecho numerado. --supersede revierte una. --decided-by owner|driver registra quién decidió, que no es quien lo tecleó — opcional aquí, y su ausencia significa not stated, nunca owner. --repo <name> (repetible) acota el hecho; sin ella el alcance sale del propio affects: de la pregunta, y de nada en caso contrario. Una respuesta que contradice a un hecho vivo igual se registra, y levanta una pregunta sobre cuál vale.
tldrx interview	Contesta en la terminal las preguntas abiertas de un run.
tldrx story reopen <id> --note "…"	Le da a una story de Build otra tanda de intentos. --for-fix abre en cambio una ronda de arreglo sobre una story que ya está done: un defecto concreto, sin consumir intento, con el mismo DoD y el mismo revisor.
tldrx story widen <id> <path>… --note "…"	Agrega rutas al touches: de una story — la forma sancionada de pasar un rechazo por límite declarado. Registra las rutas, la nota y la lista antes y después. No corre ningún agente, no gasta nada, no consume intento y no mueve el cursor. Se niega con una story done: reábrela antes con --for-fix.

Dinero

Comando	Qué hace
tldrx cost [<run>]	Lo que de verdad se cobró, por intento. --all, --json. --stories desglosa UN run por story de build: lo que costó de forma medible, el techo de spawn que el ejecutor le entregó a sus spawns, y la razón entre ambos — un cobro y un tope, en columnas separadas, que nunca se suman. No cambia ningún techo y no gasta nada; --all y --stories son dos reportes distintos y la combinación se rechaza.
tldrx budget show	Lo que al run le queda por gastar, y la autorización a la que le responde: el hecho, cada alcance autorizado y la política. Calla cuando no hay ninguna registrada.
tldrx budget raise <phase> <usd>	Mueve un techo. --take-from <phase>, --note. El techo resultante se mide contra la autorización registrada antes de que se escriba nada.
tldrx budget grant <usd> --fact <F>	Registra lo que el dueño AUTORIZÓ, para que un techo tenga a qué responderle. Es un total, no un delta; no gasta nada y no mueve ningún techo. --fact tiene que nombrar un hecho vivo: una autorización que no cita una decisión es un número que nadie dijo. --phase <p> la acota; --on-exceed <warn|block> dice qué pasa con un techo POR ENCIMA de lo autorizado, y nunca es on_exceed. Una segunda autorización reemplaza a la primera y dice qué reemplazó.

Conocimiento, salida y lo demás

Comando	Qué hace
tldrx map --refresh | --check	Reconstruye el mapa de código, o revísalo contra el código para detectar desfases.
tldrx expert list | create | train | recompute | rescore | packs	Ver Expertos. rescore vuelve a leer los archivos de conocimiento y deriva su evidencia otra vez — gratis, después de un cambio en lo que cuenta como evidencia. packs enable|disable|status es el único interruptor de los packs de stack — apagado por defecto.
tldrx seed triage / seed answer / seed apply	Parte un documento grande en varios runs.
tldrx watch list | check [<feature>]	Las tarjetas de vigilancia que produjo un run: listadas, o impresas como la checklist de post-merge y revisadas contra el código de hoy. --execute vuelve a correr los comandos que registraron las tarjetas, a través de la lista blanca del workspace.
tldrx watch arm	Espera a que el PR del run se mergee y entonces imprime esa checklist. Un poller acotado en primer plano sobre gh pr view, no un demonio.
tldrx plan sync-dod | schema	Repara los DoD de las stories después de editar workspace.yml, o imprime el contrato de story/épica/waves que hace cumplir la verificación plan.
tldrx dashboard	Mira el workspace en vivo en el navegador, o exporta una página estática. Ver Dashboard.
tldrx replay [<run>]	El log de eventos del run, contado como historia.
tldrx retro	Cierra un run y captura lo que se aprendió.
tldrx retro --all	Solo lectura, sobre TODOS los runs: qué clases de hallazgo te siguen agarrando, con conteos y un ejemplo citado de cada una. --json para la forma que lee una máquina. No escribe nada.
tldrx drive --attended | --unattended [<run>]	Imprime el mandato de sesión para manejar un run: un preflight que establece si el run está atendido, la política de compuertas y el presupuesto (y se niega a empezar sin ellos), y luego el protocolo de tres papeles, la disciplina de evidencia, qué apartar, con cuánto rigor revisar y honestidad de presupuesto. Llena cada <run> con el id, o con el único run abierto. No necesita workspace.
tldrx ship	Abre un PR desde la rama de la épica, con un cuerpo escrito para un PR: qué se entregó y qué no, los hallazgos de revisión que siguen abiertos, y el handoff del run completo dentro de un bloque <details>. Un PR por repo cuando la rama está en varios, listados al final. Si lo vuelves a correr, se salta el repo cuyo PR ya está abierto.
tldrx tickets	Refleja épicas y stories en una herramienta de tickets. Los archivos siguen siendo la fuente de verdad.
tldrx note <run> "…"	Registra una anotación del operador, sin cambiar nada más.
tldrx facts add "…" --area <id> --decided-by <owner|driver>	Registra un hecho durable y con procedencia — lo que los prompts posteriores sí vuelven a leer, para algo que ninguna pregunta pidió. --area es como cada lector le acota una coincidencia; --decided-by registra quién decidió, que no es lo mismo que quién lo escribió. Tope de 2000 caracteres: pasado eso el texto se corta, queda marcado con truncated:, y el corte se dice en stdout.

Códigos de salida

0	ok
1	error de uso o de esquema, o una verificación corrió y falló
2	rechazado — una compuerta dijo que no, o hay varios runs abiertos y no va a adivinar
3	no encontrado — no hay workspace, no hay run, no hay tarjeta con ese nombre
4	esperando a una persona — la etapa corrió y se detuvo en su compuerta
5	el subagente falló
130	Ctrl-C — se mató al subagente y la etapa volvió a ready

Cuáles de estos puede devolver un comando dado te lo dice tldrx <command> --help.

Dos convenciones que aplican en casi todos lados

• Nunca adivina a qué run te referías. Con varios abiertos y sin id, un comando que apunta a un run te los lista y se niega — sale con 2, salvo cost, que se niega con 1. run status es el que no se niega: te los lista y sale con 0, porque es la pantalla que lees para encontrar el id que todos los demás te van a pedir. Cómo se pasa ese id también cambia. next, cost, note, ship y run sobre uno abierto (attend, status, estimate, auto, unlock, cancel) aceptan un <run> posicional o --run <id>; replay y retro, nada más el posicional; approve, reject, answer, interview y run gates set, nada más --run <id>. Cualquiera de estos casos lo resuelve tldrx <command> --help.
• La salida de progreso siempre va a stderr. --ui scene|compact|plain|off (por omisión auto) cambia lo que ves mientras corre un subagente; stdout queda idéntico byte por byte en cualquier caso, así que tldrx run status --json | jq no se ve afectado.