CLI overview

The authority is your own machine: tldrx --help, and tldrx <command> --help for one command's flags, allowed values, examples and exit codes. This page is a map of the surface, not a copy of it.

This page is a curated tour: the commands you reach for, grouped by what you are trying to do. It names some flags and not others, on purpose.

For every flag — including the ones this page leaves out — see Every command and flag. That page is generated at build time from src/cli/helpText.ts, the same registry --help prints and the argv guard refuses unknown flags from, so it lists every command with every flag, every allowed value, every exit code and the environment variables, and it cannot fall behind the code.

The five you will actually type

tldrx init                  # detect the workspace, map the code, ask only the gaps
tldrx run new <slug> --scope feature --budget 25
tldrx next                  # run the next stage; it stops at a gate
tldrx answer Q1 "…"         # answer what it asked
tldrx approve --note "…"    # sign the gate; the checks are re-run first

Setting up

Command	Does
tldrx doctor	Check the local environment. The authority on what is required.
tldrx init	Detect repos, build the code map, write .tldrx/, list the gaps. Runs your build/test commands once to check them; --no-probe skips that.
tldrx interview --init	Answer the setup questions in the terminal.
tldrx install --claude	Write the /tldrx skill, hooks and status line into .claude/.
tldrx learn	The playable sandbox tutorial. No key, no network, $0.00.
tldrx update	npm i -g tldr-experts@latest, plus the CHANGELOG between the version you had and the one you now have. Any command tells you, in one line, when a newer one exists — off the hot path, cached, silent on failure, never in --json or a hook. TLDRX_UPDATE_CHECK=off turns it off for a shell, update_check: off in ~/.tldrx/config.yml for the machine.
tldrx status	Everything in this workspace waiting on a human, and the command for each.

Driving a run

Command	Does
tldrx run new <slug>	Open a piece of work. --scope, --budget, --seed, --gates, --attended-by host.
tldrx run status [<run>]	Where it is, what it is waiting on, what it cost. --json.
tldrx next [<run>]	Run the next stage. --dry-run, --prepare/--commit, --review, --check, --effort, --max-reads.
tldrx run auto [<run>]	Call next repeatedly until something needs you. --max-usd, --until, --parallel, and --notify-every / --wait-answers / --wait-gates to run it fully unattended — see Operating a run unattended.
tldrx run attend host | --none	Hand the run to a host session, or take it back.
tldrx run estimate	The one command that guesses. It says ESTIMATE.
tldrx run unlock / run cancel	Clear a stale lock; close a run for good.

Deciding

Command	Does
tldrx approve	Sign the gate. --note, --as-agent, --evidence.
tldrx reject --note "…"	Send the stage back; --stage <phase>/<stage> revokes a signature.
tldrx gate template	Write the skeleton evidence note an agent gate is signed over.
tldrx run gates set <stage>:<policy> --note "…"	The only sanctioned way to change gate policy after run new.
tldrx questions cards	The run's OPEN questions as printable decision cards — context, what the docs already decide, the options. Reads only.
tldrx questions lint	Name every question block the parser cannot see — a missed ## Qn · Title reads as absent, so everything downstream reports "0 open questions" and an auto gate signs over them. --fix rewrites them into the grammar without changing a word.
tldrx answer <Qid> "…"	Record an answer as a numbered fact. --supersede reverses one. --decided-by owner|driver records who decided it, as against who typed it — optional here, and absent means not stated, never owner. --repo <name> (repeatable) scopes the fact; without it the scope comes from the question's own affects:, and from nothing otherwise. An answer that contradicts a live fact is still recorded, and raises a question asking which holds.
tldrx interview	Answer a run's open questions in the terminal.
tldrx story reopen <id> --note "…"	Give one build story another run of attempts. --for-fix opens a fix round on a story already done — one named defect, no attempt consumed, same DoD and same reviewer.
tldrx story widen <id> <path>… --note "…"	Add paths to a story's touches: — the sanctioned way past a boundary refusal. Records the paths, the note and the list before and after. Runs no agent, spends nothing, consumes no attempt, moves no cursor. Refuses a done story: reopen it with --for-fix first.

Money

Command	Does
tldrx cost [<run>]	What was actually charged, per attempt. --all, --json. --stories breaks ONE run down by build story: what it measurably cost, the spawn ceiling the executor handed its spawns, and the ratio — a charge and a cap, in separate columns, never added. It changes no ceiling and spends nothing; --all and --stories are two different reports and the pair is refused.
tldrx budget show	What the run may still spend, and the grant it answers to: the fact, each authorized scope and the policy. Silent when no grant is recorded.
tldrx budget raise <phase> <usd>	Move a ceiling. --take-from <phase>, --note. The resulting ceiling is measured against the recorded grant before anything is written.
tldrx budget grant <usd> --fact <F>	Record what the owner AUTHORIZED, so a ceiling has something to answer to. A total, not a delta; it spends nothing and moves no ceiling. --fact must name a live fact — an authorization that cites no decision is a number nobody said. --phase <p> scopes it; --on-exceed <warn|block> says what a ceiling ABOVE the grant does, and is never on_exceed. A second grant replaces the first and says what it replaced.

Knowledge, output and the rest

Command	Does
tldrx map --refresh | --check	Rebuild the code map, or check it against the code for drift.
tldrx expert list | create | train | recompute | rescore | packs	See Experts. rescore re-reads the knowledge files and derives their evidence again — free, after a change to what counts as evidence. packs enable|disable|status is the one switch for the stack packs — off by default.
tldrx seed triage / seed answer / seed apply	Split a big document into several runs.
tldrx watch list | check [<feature>]	The watcher cards a run produced: listed, or printed as the post-merge checklist and re-checked against the code now. --execute re-runs the commands the cards recorded, through the workspace allowlist.
tldrx watch arm	Wait for the run's shipped PR to merge, then print that checklist. A bounded foreground poller over gh pr view — not a daemon.
tldrx plan sync-dod | schema	Repair story definitions of done after editing workspace.yml, or print the story/epic/waves contract the plan check enforces.
tldrx dashboard	Watch the workspace live in a browser, or export one static page. See Dashboard.
tldrx replay [<run>]	The run's event log as a narrative.
tldrx retro	Close a run and capture what was learned.
tldrx retro --all	Read-only across EVERY run: which finding classes keep catching you, with counts and one cited example each. --json for the machine shape. Writes nothing.
tldrx drive --attended | --unattended [<run>]	Print the session mandate for driving a run — a preflight that establishes attendedness, the gate policy and the budget (and refuses to start without them), then the three-role protocol, evidence discipline, parking, review calibration and budget honesty. Fills every <run> in from the id, or from the one open run. Needs no workspace.
tldrx ship	Open a PR from the epic branch, with a body written for a PR: what shipped, what did not, the reviewer findings still open, and the run's handoff whole inside a <details> block. One PR per repo when the branch is in several, listed at the end. Re-running skips a repo whose PR is already open.
tldrx tickets	Mirror epics and stories to a ticket tool. Files stay the source of truth.
tldrx note <run> "…"	Record one operator annotation, changing nothing else.
tldrx facts add "…" --area <id> --decided-by <owner|driver>	Record one durable, provenanced fact — what later prompts actually read back, for something no question asked about. --area is how every reader scopes a match; --decided-by records who decided, as against who typed it. Capped at 2000 characters: past that the text is cut, marked truncated:, and the cut is named on stdout.

Exit codes

0	ok
1	usage or schema error, or a check ran and failed
2	refused — a gate said no, or several runs are open and it will not guess
3	not found — no workspace, no run, no card by that name
4	awaiting a human — the stage ran and stopped at its gate
5	the sub-agent failed
130	Ctrl-C — the sub-agent was killed and the stage is back to ready

Which of these a given command can return is listed by tldrx <command> --help.

Two conventions that apply almost everywhere

• It never guesses which run you meant. With several open and no id, a run-targeting command lists them and refuses — exit 2, except cost, which refuses at 1. run status is the one that does not refuse: it lists them and exits 0, because it is the screen you read to find the id every other command wants. How you pass that id varies. next, cost, note, ship, and run on an open one (attend, status, estimate, auto, unlock, cancel) take either a positional <run> or --run <id>; replay and retro take the positional only; approve, reject, answer, interview and run gates set take --run <id> only. tldrx <command> --help settles any of them.
• Progress output goes to stderr, always. --ui scene|compact|plain|off (default auto) changes what you see while a sub-agent runs; stdout is byte-identical either way, so tldrx run status --json | jq is unaffected.