# `tatbot` command reference

<!-- GENERATED by `scripts/tatbot schema --md > docs/cli.md`. Do not edit; `scripts/check cli` fails when stale. -->

Offline CLI workflows for public development and replay. Maintainers can inspect the complete machine-readable schema with `tatbot schema --json`.

```
tatbot [global flags] <noun> [verb] [args] [-- passthrough args]
```

Global flags may appear anywhere before the first `--`, as `--flag value` or `--flag=value`, unless a declared command option owns that spelling: `--json`, `--dry-run`, `--explain`, `-q`, `-v`. Stating one twice with different values is a usage error.

`--json` execution is supported only by commands declaring structured output in `schema --json`; all commands support JSON plans and explanations. Use `--output FILE` for draw report destinations. Backend flags on structured commands require `--`; tokens after it are preserved.

CLI-owned exit codes are below. Executed backends and SSH retain their own exit codes and error output; backend failures are not remapped to 1.

## Exit codes

| code | meaning |
| --- | --- |
| 0 | ok |
| 1 | underlying tool failed |
| 2 | usage error |
| 3 | safety gate refused |
| 4 | wrong node for this verb |
| 5 | hardware unreachable |
| 6 | busy |

## Safety tiers

| tier | meaning | gates |
| --- | --- | --- |
| `offline` | files only | — |

## Verbs


### `tatbot completion` — generate opt-in shell completion

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `completion bash` | `offline` | this checkout | native | print Bash completion generated from canonical command metadata |

### `tatbot body` — immutable human body model assets and cache audit

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `body export` | `offline` | this checkout | `web/inkmap/tools/export-soma.py` | bake genuine articulated SOMA poses into the shared Inkmap and simulation catalog (`--` → export-soma.py) |
| `body bootstrap` | `offline` | this checkout | native | copy a pinned, pre-downloaded MHR and SOMA allowlist into an explicit verified cache |
| `body audit` | `offline` | this checkout | native | read and hash every byte in an explicit MHR and SOMA cache without deserializing it |

### `tatbot teleop` — leader→follower teleoperation

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `teleop poses` | `offline` | this checkout | `scripts/vision/teleop_poses.py` | export measured follower tip poses and host read timestamps from a flight log (`--ee-tool`) |
| `teleop analyze` | `offline` | this checkout | `cpp/teleop/analyze_log.py` | loop-timing stats from a .wxtl without a GUI |

### `tatbot rollout` — analyze policy rollouts and recorded data

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `rollout analyze` | `offline` | this checkout | `scripts/il_analyze_rollout.py` | did the pen draw the shape, did the loop keep time (`--` → il_analyze_rollout.py) |
| `rollout bench` | `offline` | this checkout | `scripts/eval/wire_bench.py`, `scripts/eval/trajectory_plausibility.py` | no-robot checks of the serving path (wire bench / plausibility) (`--` → wire_bench.py / trajectory_plausibility.py) |
| `rollout contract` | `offline` | this checkout | `scripts/eval/checkpoint_contract.py` | the input/action contract stored with a checkpoint (`--` → checkpoint_contract.py) |

### `tatbot sim` — scenario, dataset, evaluation and render tools

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `sim list` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/factory.py` | the named distributions the factory can generate |
| `sim generate` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/factory.py`, `python/tatbot_sim/src/tatbot_sim/generate.py` | generate one named distribution into a LeRobot v3 dataset (`--` → tatbot_sim.generate (tyro)) |
| `sim sample` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/cli.py` | materialize a bounded artwork suite of posed-body scenarios (`--` → tatbot_sim.inkmap.cli sample) |
| `sim compile` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/cli.py` | compile one Inkmap placement into a replayable posed-body scenario (`--` → tatbot_sim.inkmap.cli compile) |
| `sim perception` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/perception_dataset.py` | render audited privileged Inkmap perception labels on CPU (`--` → tatbot_sim.inkmap.cli perception) |
| `sim perception-audit` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/perception_audit.py` | audit an existing privileged Inkmap perception corpus (`--` → tatbot_sim.inkmap.perception_audit) |
| `sim pilot-plan` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/pilot.py`, `config/inkmap/synthetic-pilot.json` | write and audit the full Inkmap synthetic-pilot ledger (`--` → tatbot_sim.inkmap.cli pilot-plan) |
| `sim pilot-audit` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/pilot.py` | audit an existing Inkmap synthetic-pilot ledger (`--` → tatbot_sim.inkmap.cli pilot-audit) |
| `sim parity` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/parity_evidence.py`, `web/inkmap/tools/surface_parity.ts` | produce browser/simulator Inkmap mapping and mask parity evidence (`--` → tatbot_sim.inkmap.parity_evidence) |
| `sim materialize` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/cli.py`, `web/inkgen/app.py` | generate and trace immutable Inkgen SVG artifacts before scenario compilation (`--` → tatbot_sim.inkmap.cli materialize-designs) |
| `sim recipes` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/recipes.py` | expand a frozen artwork library into reproducible scenario recipes (`--` → tatbot_sim.inkmap.cli recipes) |
| `sim recipes-status` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/recipes.py` | read a recipe ledger and audit its splits without any network (`--` → tatbot_sim.inkmap.cli recipes-status) |
| `sim resolve` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/cli.py`, `web/inkmap/src/core/lang.ts` | resolve a typed InkLang request into one replayable posed-body scenario (`--` → tatbot_sim.inkmap.cli resolve) |
| `sim qualify-artwork` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/artwork_qualification.py` | qualify shared artwork paint, duration, and simulated deposition (`--` → tatbot_sim.inkmap.artwork_qualification) |
| `sim eval dataset` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/eval_cli.py` | score judged expert datasets and write a screen report (`--` → tatbot_sim.eval_cli) |
| `sim eval policy` | `offline` | this checkout | `scripts/eval/sim_policy_eval.py` | run a checkpoint through a local ManiSkill worker and the async wire (`--` → sim_policy_eval.py) |
| `sim preview` | `offline` | this checkout | `scripts/sim_preview.py` | preview what the factory would generate, no dataset written (`--` → sim_preview.py (tyro)) |
| `sim reach` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/audit_reach.py` | audit tool IK reach over the domain-randomization distribution, headless (`--` → tatbot_sim.audit_reach (tyro)) |
| `sim cinematic` | `offline` | this checkout | `scripts/sim_cinematic.py` | path-traced takes of a distribution for showing outside the lab (`--` → sim_cinematic.py (tyro)) |
| `sim viewer` | `offline` | this checkout | `scripts/render_viewer.py` | build an HTML viewer over render directories with system Python (`--` → render_viewer.py) |
| `sim audit` | `offline` | this checkout | `scripts/sim_dataset_audit.py` | audit a generated dataset or a night of shards (`--` → sim_dataset_audit.py (tyro)) |
| `sim samples` | `offline` | this checkout | `scripts/sim_dataset_samples.py` | extract stills and short clips from a dataset or shards (`--` → sim_dataset_samples.py (tyro)) |
| `sim showcase-artwork` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/showcase.py` | materialize five typed artwork previews for the Inkmap pose gallery (`--` → tatbot_sim.inkmap.showcase) |

### `tatbot travel` — travel demo previews and synthetic tracing episodes

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `travel preview` | `offline` | this checkout | native | render a travel episode and optional camera/hand inspection views without a dataset (`--` → travel preview) |
| `travel generate` | `offline` | this checkout | native | generate travel LeRobot episodes with canonical SOMA surface-address labels (`--` → travel generate) |
| `travel trace` | `motion-auto` | this checkout | native | scan the practice forearm with the blue wrist camera and follow a stroke of ink at the laser's hover (`--` → trace) |

### `tatbot calib` — native arm measurements and retained overhead registration

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `calib register-fit` | `offline` | this checkout | `scripts/vision/native_registration.py` | fit an unadopted overhead registration from original native holds and shared geometry |

### `tatbot vision` — offline vision processing and calibration

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `vision depth compare` | `offline` | this checkout | `scripts/vision/depth_compare.py` | compare filters on a retained raw scan burst |
| `vision board witness` | `offline` | this checkout | `scripts/vision/board_witness.py`, `scripts/vision/board_mount_witness.py` | compare retained board depth with independently measured fiducial size |
| `vision stencil generate` | `offline` | this checkout | `scripts/lib/stencil_generate.py` | generate a stencil frame: the coded flower-of-life (default) or the legacy floral frame, with print sheets |
| `vision stencil reference` | `offline` | this checkout | `scripts/lib/stencil_reference.py` | export a tracking manifest for existing generated stencil artwork |
| `vision stencil print` | `offline` | this checkout | `scripts/lib/stencil_print.py` | print sheets for a stencil: millimetre rulers, a pattern and size label, stencil-app PNG and paper PDFs |
| `vision stencil replay` | `offline` | this checkout | `scripts/vision/stencil_observe.py` | replay known stencil tracking and optional advisory surface candidates |
| `vision stencil observe` | `sensor` | this checkout | `scripts/vision/stencil_observe.py` | observe known stencils from an existing visiond owner socket |
| `vision stencil bench` | `offline` | this checkout | `scripts/vision/stencil_bench.py` | score a stencil design and tracker in mm on seeded 2-D transfer scenes (tier 0) |
| `vision tags print` | `offline` | this checkout | `scripts/vision/generate_wrist_tags.py` | render the wrist-tag print sheet (`--` → generate_wrist_tags.py) |
| `vision handeye d405` | `offline` | this checkout | `scripts/vision/d405_handeye_plane.py` | plane-route hand-eye for the wrist D405s: fit depth planes against the touched-off paper (`--` → d405_handeye_plane.py) |

### `tatbot design` — an image or an SVG to a portable design, without a browser

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `design generate` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/design_cli.py`, `web/inkgen/app.py` | ask the generator for one tattoo-flash PNG (starting it if it is not up) (`--` → tatbot_sim.inkmap.design_cli generate) |
| `design trace` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/design_cli.py`, `web/inkmap/tools/artwork.ts` | retired tracer: use drawingbot generate and import acquired artwork.json (`--` → tatbot_sim.inkmap.design_cli trace) |
| `design place` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/design_cli.py`, `web/inkmap/tools/artwork.ts` | place one artwork on a plane or cylinder chart as a portable design (`--` → tatbot_sim.inkmap.design_cli place) |
| `design check` | `offline` | this checkout | `python/tatbot_sim/src/tatbot_sim/inkmap/design_cli.py`, `web/inkmap/tools/artwork.ts` | validate a design with the browser reader and report its material footprint (`--` → tatbot_sim.inkmap.design_cli check) |

### `tatbot drawingbot` — DrawingBotV3 stroke experiments and preference review

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `drawingbot generate` | `offline` | this checkout | `scripts/drawingbot.sh`, `scripts/drawingbot.py`, `scripts/lib/drawing_python.sh`, `scripts/lib/drawing_python.py`, `scripts/lib/drawingbot/artifacts.py`, `scripts/lib/drawingbot/bridge.py`, `scripts/lib/drawingbot/replay.py`, `scripts/lib/drawingbot/recipe.py`, `scripts/lib/drawingbot/container.py`, `scripts/lib/drawingbot/job.py`, `scripts/lib/drawingbot/pens.py` | generate one physical DBV3 drawing with verified settings and a saved native recipe |
| `drawingbot export` | `offline` | this checkout | `scripts/drawingbot.sh`, `scripts/drawingbot.py`, `scripts/lib/drawing_python.sh`, `scripts/lib/drawing_python.py`, `scripts/lib/drawingbot/artifacts.py`, `scripts/lib/drawingbot/bridge.py`, `scripts/lib/drawingbot/replay.py`, `scripts/lib/drawingbot/recipe.py`, `scripts/lib/drawingbot/container.py` | verify and replay native SVG acquisition only, without ROS compilation |
| `drawingbot container` | `offline` | this checkout | `scripts/drawingbot.sh`, `scripts/drawingbot.py`, `scripts/lib/drawing_python.sh`, `scripts/lib/drawing_python.py`, `scripts/lib/drawingbot/artifacts.py`, `scripts/lib/drawingbot/bridge.py`, `scripts/lib/drawingbot/replay.py`, `scripts/lib/drawingbot/recipe.py`, `scripts/lib/drawingbot/container.py` | build, smoke-test or run the private mounted-app acquisition container |

### `tatbot inkmap` — ground InkLang placements and preview tattoos on canonical bodies

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `inkmap dev` | `offline` | this checkout | `scripts/inkmap_dev.sh`, `web/inkmap/package.json` | the tattoo preview app on this machine (`--` → inkmap_dev.sh) |
| `inkmap resolve` | `offline` | this checkout | `web/inkmap/tools/resolve.ts`, `config/inkmap/inklang-resolution.schema.json`, `web/inkmap/package.json` | resolve InkLang placement text to a canonical rest-surface anchor as JSON |

### `tatbot inkgen` — generate tattoo artwork for Inkmap

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `inkgen batch` | `offline` | this checkout | `web/inkgen/batch.py`, `python/tatbot_sim/src/tatbot_sim/inkmap/inkgen_materialize.py` | run or resume a resumable artwork generation job (`--` → tatbot_sim.inkmap.cli batch) |
| `inkgen batch-status` | `offline` | this checkout | `web/inkgen/batch.py` | read a generation job's ledger: requested, accepted, refused, failed, duplicate (`--` → tatbot_sim.inkmap.cli batch-status) |

### `tatbot profile` — inspect and validate hardware profiles

| verb | tier | runs on | wraps | summary |
| --- | --- | --- | --- | --- |
| `profile show` | `offline` | this checkout | `scripts/lib/tatbot_profile.py` | the resolved hardware profile: backend, arms, e-stop, provenance |
| `profile list` | `offline` | this checkout | `scripts/lib/tatbot_profile.py` | the profiles this checkout carries |
| `profile check` | `offline` | this checkout | `scripts/lib/tatbot_profile.py` | can the resolved profile drive hardware? (exit 3 if not) |

## Compatibility spellings

These deprecated forms translate to the same canonical handler. They warn once on stderr. They remain for at least 30 days and two reviewed releases after 2026-09-05, whichever is longer; removal also requires consumer review and a release note.

| deprecated form | canonical form |
| --- | --- |
| `tatbot sim compile --sample N` | `tatbot sim sample --count N` |
| `tatbot sim preview --reach` | `tatbot sim reach` |
| `tatbot sim cinematic --viewer DIR…` | `tatbot sim viewer DIR…` |
| `tatbot sim audit --samples DATASET` | `tatbot sim samples DATASET` |
| `tatbot sim eval --policy-rollout -- ARGS` | `tatbot sim eval policy -- ARGS` |
| `tatbot sim eval DATASET…` | `tatbot sim eval dataset DATASET…` |

## Bash completion

Generate and source completion explicitly (Bash 4+):

```sh
tatbot completion bash > /tmp/tatbot-completion.bash
source /tmp/tatbot-completion.bash
```

Generation prints shell code; it does not install anything or edit shell startup files. Completion is generated from the canonical commands, options and choices.


## Examples

```
tatbot completion bash
tatbot body export --python '<path>' -- --help
tatbot body bootstrap --spec config/body-models/mhr-soma-v1.json --cache-dir '<path>' --source-dir '<path>'
tatbot body audit --spec config/body-models/mhr-soma-v1.json --cache-dir '<path>'
tatbot teleop poses flight.wxtl --out '<path>' --urdf urdf/tatbot.urdf --workspace config/workspace.yaml
tatbot teleop analyze '<path>'
tatbot rollout analyze '<path>'
tatbot rollout bench wire -- --help
tatbot rollout contract '<path>'
tatbot sim list
tatbot sim generate paper-draw -- --out-dir '<path>' --num-episodes 8
tatbot sim sample --count 3 -- --output-dir '<path>'
tatbot sim compile config/inkmap/examples/forearm-placement-v6.json -- --pose reclined-left-arm-supported --output '<path>'
tatbot sim perception '<path>' -- --output-dir '<path>'
tatbot sim perception-audit '<path>'
tatbot sim pilot-plan -- --output-dir '<path>' --seed 42
tatbot sim pilot-audit '<path>'
tatbot sim parity -- --output '<path>'
tatbot sim materialize -- --help
tatbot sim recipes -- --help
tatbot sim recipes-status -- --help
tatbot sim resolve 'a dbv3-orbit on the left forearm' -- --design-id dbv3-orbit --size-mm 30 30 --seed 42 --output-dir '<path>'
tatbot sim qualify-artwork -- --output-dir '<path>'
tatbot sim eval dataset '<path>' -- --output-dir '<path>'
tatbot sim eval policy -- --client-mode hold-control --output-dir '<path>'
tatbot sim preview -- --help
tatbot sim reach -- --help
tatbot sim cinematic -- --help
tatbot sim viewer '<path>' '<path>'
tatbot sim audit -- --help
tatbot sim samples '<path>' -- --out '<path>'
tatbot sim showcase-artwork -- --output-dir '<path>'
tatbot travel preview -- --help
tatbot travel generate -- --help
tatbot travel trace -- scan
tatbot calib register-fit --python '<path>' --arm blue --capture '<path>' --bundle '<path>' --setup-id table-setup --out '<path>'
tatbot vision depth compare --capture capture-1.npz --settings filters.json
tatbot vision board witness --python '<path>' --capture capture.json --inventory fiducials.json --measurement measurement.json --color-sensor wrist_color --out '<path>'
tatbot vision stencil generate --seed 101 --output '<path>'
tatbot vision stencil reference --settings stencil/settings.json
tatbot vision stencil print --seed 101 --output '<path>'
tatbot vision stencil replay --reference stencil/tracking.json --instance skin-a --frames frames.jsonl --output '<path>'
tatbot vision stencil observe --reference stencil/tracking.json --instance skin-a --socket '<path>' --sensor rgb --output '<path>'
tatbot vision stencil bench --seed tatbot-42 --tracker sift
tatbot vision tags print -- --help
tatbot vision handeye d405 --self-test
tatbot design generate 'a swallow carrying a rose' --out '<path>'
tatbot design trace
tatbot design place '<path>' --target cylinder --radius-mm 40 --canvas-mm 80 110 --out '<path>'
tatbot design check '<path>'
tatbot drawingbot generate '<path>' --out '<path>' --app '<path>'
tatbot drawingbot export '<path>' --out '<path>' --app '<path>'
tatbot drawingbot container build --out '<path>'
tatbot inkmap dev
tatbot inkmap resolve --prompt 'left upper inner forearm'
tatbot inkgen batch --output-dir '<path>' --subject 'a heron' --count 4
tatbot inkgen batch-status --output-dir '<path>'
tatbot profile show
tatbot profile list
tatbot profile check
```