# Tracetoon CLI (for agents)

<!-- Generated by scripts/agent-surfaces.ts from the command definitions in src/program.ts. Do not edit by hand. -->

Write PR descriptions from the agent session logs already on your machine. `tracetoon commands --json` prints this list as JSON.
Every command accepts `--json`; exit codes and error codes are in
[errors.md](https://tracetoon.ai/docs/agents/errors.md). Effects: `publishes` posts to GitHub,
`sends-data` sends text to an outside service, `may-cost` can cost the
user money, `installs` writes into agents' folders or replaces Tracetoon.

## `tracetoon build-info`

runtime identity and supported workflow capabilities

## `tracetoon integrations`

the agents Tracetoon supports, and where each gets the skill

| Option | Description |
| --- | --- |
| `--skill-targets` | print "<agents>\|<skill folder>" for each present agent (used by the installers) |

## `tracetoon task`

register and finish a cohesive local change

## `tracetoon task begin`

| Option | Description |
| --- | --- |
| `--run <id>` | resume this task |
| `--base <ref>` | PR base |
| `--session <id>` | actual host session id |
| `--transcript <path>` | active host transcript |
| `--reason <text>` | reason work is unfinished |
| `--checks <names>` | comma-separated applicable check names |
| `--no-checks <reason>` | explain why no local checks apply |

## `tracetoon task complete`

| Option | Description |
| --- | --- |
| `--run <id>` | resume this task |
| `--base <ref>` | PR base |
| `--session <id>` | actual host session id |
| `--transcript <path>` | active host transcript |
| `--reason <text>` | reason work is unfinished |
| `--checks <names>` | comma-separated applicable check names |
| `--no-checks <reason>` | explain why no local checks apply |

## `tracetoon task defer`

| Option | Description |
| --- | --- |
| `--run <id>` | resume this task |
| `--base <ref>` | PR base |
| `--session <id>` | actual host session id |
| `--transcript <path>` | active host transcript |
| `--reason <text>` | reason work is unfinished |
| `--checks <names>` | comma-separated applicable check names |
| `--no-checks <reason>` | explain why no local checks apply |

## `tracetoon task block`

| Option | Description |
| --- | --- |
| `--run <id>` | resume this task |
| `--base <ref>` | PR base |
| `--session <id>` | actual host session id |
| `--transcript <path>` | active host transcript |
| `--reason <text>` | reason work is unfinished |
| `--checks <names>` | comma-separated applicable check names |
| `--no-checks <reason>` | explain why no local checks apply |

## `tracetoon check [command...]`

run validation and record exact tested content

| Option | Description |
| --- | --- |
| `--run <id>` | task run (required) |
| `--name <name>` | check name |
| `--cwd <path>` | directory inside the repository |
| `--skip <reason>` | explicit CI-only or unavailable check |
| `--force` | rerun even if unchanged |
| `--input <path>` | also fingerprint an ignored generated artifact (repeatable) (default: `[]`) |

## `tracetoon images`

image routes for comics: which can draw, which are approved, and what to do next

**Acts outside the machine:** sends-data, may-cost (with --approve or --test).

| Option | Description |
| --- | --- |
| `--approve <route>` | record the user agreed to send comic prompts to this route |
| `--test [route]` | draw one small test picture (no repo content) with this route |
| `--consent` | with --test: the user agreed to this route |
| `--brief` | one line, for the installers |
| `--dismiss` | don't ask about image setup again on this machine (asked again only if a working route breaks) |

## `tracetoon update`

check for a newer release and install it in place (skill, runtime, hooks)

**Acts outside the machine:** installs.

| Option | Description |
| --- | --- |
| `--check` | only report whether a newer release exists |
| `--exit-code` | with --check: exit 10 when an update is available |
| `--to <version>` | install this release (also how to roll back) |
| `--channel <channel>` | stable (releases only) or latest (includes candidates) |
| `--quiet` | print nothing (used by background checks) |
| `--auto` | install in the background, only when autoUpdate is install |

## `tracetoon doctor`

check git, gh and which agent logs are on this machine

| Option | Description |
| --- | --- |
| `--probe` | also list record types the log readers do not recognize |
| `--strict` | exit 6 if a required check fails; with --probe: exit 5 if unknown record types are found |

## `tracetoon scan`

list agent sessions that match the current branch, with scores

| Option | Description |
| --- | --- |
| `--base <ref>` | base branch (default: the PR base or the repo default) |
| `--offline` | do not ask GitHub for an existing PR |

## `tracetoon digest`

start a run: build the redacted trace digest for this branch

| Option | Description |
| --- | --- |
| `--run <id>` | refresh an existing run, preserving its description and comic |
| `--base <ref>` | base branch, or <remote>/<branch> for one only another remote has |
| `--include <ids>` | session refs or ids to include |
| `--exclude <ids>` | session refs or ids to leave out |
| `--budget <tokens>` | approximate token budget |
| `--offline` | do not ask GitHub for an existing PR |

## `tracetoon expand <refs...>`

print full redacted evidence for a session, S/D/P/R/V fact or commit:<sha>

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |

## `tracetoon query [words...]`

ask this run's evidence graph: a named query (brief, outline, why <path|H#>, verified, unverified, unexplained, turn <S#>, stale <R#>, dead-ends, pushback, schema) or --cypher

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--cypher <query>` | a read-only Cypher query (MATCH ... RETURN ...) |
| `--params <json>` | parameters for --cypher, as a JSON object |
| `--all` | print every row (default: at most 60 per section) |
| `--layout <layout>` | brief only: toon, neighborhood or neighborhood-wide (default: the layout prepare chose for the run) |

## `tracetoon prepare`

prepare digest and contribution context from one repository snapshot

| Option | Description |
| --- | --- |
| `--run <id>` | refresh an existing run |
| `--base <ref>` | base branch, or <remote>/<branch> for one only another remote has |
| `--include <ids>` | session refs or ids to include |
| `--exclude <ids>` | session refs or ids to exclude |
| `--budget <tokens>` | approximate digest token budget |
| `--offline` | disable GitHub lookups and external contributor research |
| `--layout <layout>` | evidence brief layout for this run: toon (default), neighborhood or neighborhood-wide; later commands use it |
| `--graph-search <mode>` | search links in the evidence graph (SKILL "Graph search:"): fulltext (default; bm25 is an alias) or none; refreshes of the run keep it |
| `--review-passes <n>` | review plan (SKILL "Review passes:"): fresh reviewer passes from distinct reviewer agents that publish requires (default 1) |
| `--review-lenses <list>` | review plan (SKILL "Review lenses:"): a, b, c or none; one reviewer pass per lens |
| `--reviewer-model <name>` | review plan (SKILL "Reviewer model:"): every pass must record this model; "same" or omitted for none |
| `--reviewer-effort <level>` | review plan (SKILL "Reviewer effort:"): low, medium, high, xhigh, max or default; every pass must record it |
| `--reviewer-runner <runner>` | review plan (SKILL "Reviewer runner:"): agent (the drafter starts the reviewer) or tracetoon (tracetoon review run starts it with the model pinned; publish requires that) |
| `--review-recheck <mode>` | review plan (SKILL "Review recheck:"): once (each reviewer confirms the correction round), contested (only reviewers whose findings were rejected) or none; publish never requires a recheck |

## `tracetoon source <paths...>`

snapshot base/head source files and emit immutable review references

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--revision <revision>` | prepared base or head (default: `"head"`) |

## `tracetoon context`

prepare contributor research, the submitted diff, template, policy and PR context

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--offline` | disable GitHub lookups and require offline contributor research |

## `tracetoon guidance`

contributor research handoffs

## `tracetoon guidance check`

validate guidance.json citations, discovery chains and local snapshots

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |

## `tracetoon render`

freeze body.md into the final PR body, scan it, and report the review results

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--allow-findings` | post even though the leak scan found something (only when the user says it is fine) |
| `--no-comic` | leave the comic out even if one was rendered |
| `--retitle` | replace a title a person chose (only after the user agrees) |
| `--lean` | lean brief path: drafted inline from the evidence brief, no separate reviewer needed to publish |
| `--check` | brief path: check the draft against the evidence brief before the slim review |
| `--reviewed` | reviewed brief path: drafted inline from the evidence brief, then checked by one slim reviewer (reviewer-notes.md) |

## `tracetoon review-packet`

write review-packet.md for the lean reviewer: numbered body, brief rows, hunk owners and the diff

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--lean` | the lean packet (the only one) |
| `--lens <a\|b\|c>` | a lens reviewer packet (review-packet-<lens>.md): the lens checklist first, unused brief rows left out |

## `tracetoon review`

lean reviewer handoffs

## `tracetoon review run`

run the lean reviewer as a codex exec session pinned to the review plan's reviewer model, verify the model from its rollout, and import its findings

**Acts outside the machine:** sends-data, may-cost.

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--lens <a\|b\|c>` | run the lens reviewer (review-packet-<lens>.md, reviewer-lens-<lens>.md) |
| `--recheck` | confirmation round: resume the same reviewer session with the changed body lines and its previous findings |
| `--model <name>` | reviewer model when the review plan names none (must equal the plan otherwise) |
| `--effort <level>` | reviewer effort when the review plan names none (must equal the plan otherwise) |
| `--all` | run every pass the review plan requires (one per lens plus the general passes) in parallel, import each, and write one merged list (review-findings-merged.md); with --recheck, recheck them |
| `--fresh` | with --all: rerun passes already imported for the current body too |
| `--note <text>` | with --recheck: your rejections and the diff lines behind them, passed to the reviewer |

## `tracetoon review merge`

merge the findings of every imported reviewer pass into one deduplicated, ordered list (review-findings-merged.md), capped at 12 lines

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |

## `tracetoon review import`

turn the lean reviewer's review-findings.json into review.json v2 for the current render

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--findings <path>` | findings file (default: <run>/review-findings.json) |
| `--agent-id <id>` | the reviewer's real host agent id (overrides the file) |
| `--reviewer-model <name>` | the model the reviewer ran on (SKILL "Reviewer model:" line); recorded as reviewer.model |
| `--reviewer-effort <level>` | the effort the reviewer ran at (SKILL "Reviewer effort:" line); recorded on the pass |
| `--pass <n>` | which reviewer pass this is (default: this reviewer's earlier pass with the same lens, else the next) |
| `--lens <a\|b\|c>` | the lens this reviewer checked (default findings file: review-findings-<lens>.json) |
| `--rebind` | rebuild review.json for the current render from the passes already imported (claims whose quote is gone count as fixed) |

## `tracetoon publish`

create or update the PR with exactly what was rendered

**Acts outside the machine:** publishes.

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--push` | push the branch if GitHub does not have the rendered revision |
| `--no-push` | require the rendered revision to already be on the remote |
| `--draft` | open the PR as a draft |
| `--hosting <how>` | where the comic image goes: auto, branch or attach |
| `--no-review` | publish a checked brief-path draft without the slim review (only when the user asked for the cheapest run; recorded) |
| `--accept-open` | publish although the last render listed sentences to fix or brief rows to cover (recorded) |
| `--dry-run` | check everything and print what publishing would do (gh calls, target, title), without pushing or posting |

## `tracetoon comic`

make this PR's comic

## `tracetoon comic skip`

record why this PR has no comic when one was expected (the user declined, or drawing kept failing)

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--reason <text>` | why, in the user's terms (shown after publishing) |
| `--mcp` | recorded by the MCP server, which cannot draw |

## `tracetoon comic check`

check comic.json before any art is made

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |

## `tracetoon comic prompts`

print the page (or panel) prompts for the host agent's own image tool

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--lettering <how>` | model (one whole page, default) or overlay (text-free panels) |

## `tracetoon comic art`

make the comic art with Codex, Antigravity, OpenAI or Gemini, after consent (exit code 5: no approved route)

**Acts outside the machine:** sends-data, may-cost.

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--provider <name>` | auto, codex, antigravity, openai or gemini (default: `"auto"`) |
| `--consent` | the user agreed to send comic prompts to this provider |
| `--force` | redraw panels that already exist |
| `--lettering <how>` | model (the image model letters the page) or overlay (Tracetoon draws bubbles) |
| `--repair <instruction>` | edit the current page with this one change instead of redrawing it (from comic loop) |
| `--reflow` | same script, a layout whose panels are wide enough to read on a phone; then redraw |

## `tracetoon comic reroll`

redraw the page in a different style (or the one given), keeping the story

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--style <style>` | use this style (an idea id or any description) instead of a fresh one |
| `--format <id>` | also switch to this format |
| `--palette <name>` | also switch the palette: full-color, bw-accent, duotone, limited |

## `tracetoon comic render`

lay out panels and speech bubbles into out/comic.png

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |

## `tracetoon comic loop`

judge the rendered comic with fresh AI readers and say what to do next: judge, repair one thing, or stop (keeps the better version)

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--creative` | experimental: also rewrite a flat joke or weak script automatically (off by default) |

## `tracetoon comic loop-import`

record a judge subagent's answer for a comic loop task

| Option | Description |
| --- | --- |
| `--run <id>` | run id (default: latest) |
| `--task <id>` | the task comic loop printed, e.g. observe:c1 (required) |
| `--file <path>` | the answer file (default: the task's result.json) |
| `--agent-id <id>` | the judge subagent's real id |

## `tracetoon export`

write the PR attribution as an Agent Trace record (agent-trace.dev)

| Option | Description |
| --- | --- |
| `--agent-trace` | Agent Trace JSON (the only format today) (default: `true`) |
| `--base <ref>` | base branch |
| `--offline` | do not ask GitHub for an existing PR |

## `tracetoon status`

is Tracetoon on here, which setting decided, and which agents have the PR hook

## `tracetoon on`

turn Tracetoon on for your PRs (default: everywhere for you)

| Option | Description |
| --- | --- |
| `--repo` | for everyone in this repo (.github/tracetoon.json) |
| `--local` | for this repo on this machine only (git config) |

## `tracetoon off`

turn Tracetoon off for your PRs (default: everywhere for you)

| Option | Description |
| --- | --- |
| `--repo` | for everyone in this repo (.github/tracetoon.json) |
| `--local` | for this repo on this machine only (git config) |

## `tracetoon hook`

the agent hook that routes PRs through Tracetoon

## `tracetoon hook lifecycle`

| Option | Description |
| --- | --- |
| `--agent <agent>` | claude, codex, antigravity, factory, copilot, cursor, opencode, kilo, kiro, cline, junie, goose, qwen, crush, amp (required) |
| `--event <event>` | SessionStart, PreToolUse, PostToolUse or Stop (required) |

## `tracetoon hook pre-pr`

called by agents before shell commands; routes PR creation through Tracetoon

| Option | Description |
| --- | --- |
| `--agent <agent>` | claude, codex, antigravity, factory, copilot, cursor, opencode, kilo, kiro, cline, junie, goose, qwen, crush, amp (required) |

## `tracetoon hook install`

register the PR hook with every agent that supports one

**Acts outside the machine:** installs.

| Option | Description |
| --- | --- |
| `--program <path>` | program the hook should run (default: this one) |

## `tracetoon hook uninstall`

remove the PR hook from every agent

**Acts outside the machine:** installs.

## `tracetoon config`

show or change settings

## `tracetoon config get [key]`

## `tracetoon config set <key> <value>`

## `tracetoon setup`

install the skill shipped with this runtime into each agent's skill folder, and the PR hook

**Acts outside the machine:** installs.

| Option | Description |
| --- | --- |
| `--agent <id>` | only this agent (repeatable; see tracetoon integrations) (default: `[]`) |
| `--no-hook` | leave the PR hook alone |

## `tracetoon guide`

how an agent should use Tracetoon (the "Using Tracetoon" part of AGENTS.md)

## `tracetoon feedback`

print a link to a prefilled GitHub issue with a redacted doctor summary (never submits it)

| Option | Description |
| --- | --- |
| `--title <title>` | issue title |
| `--open` | open the link in the browser |

## `tracetoon mcp`

serve Tracetoon to MCP hosts on stdin/stdout: status, prepare and publish tools, and the skill as resources

**Acts outside the machine:** publishes (when a client calls tracetoon_publish_pr with dryRun false).

## `tracetoon commands`

every command and option, with which ones act outside the machine
