# CLI

URL: https://tuimark.dev/reference/cli

> The tuimark command-line interface, its commands, flags and exit codes.

{/* Generated by docs/scripts/generate.mjs from `tuimark --help`. Do not edit by hand: run `task docs-gen`. */}

```text
tuimark — a view language for terminals

usage:
  tuimark dump     FILE [--cols 80] [--rows 24] [--format text|json] [--data FILE.json]
                        [--cells] [--styles] [--strict] [--theme dark|light]
  tuimark validate FILE [--json] [--strict] [--catalog FILE] [--data FILE.json] [--theme dark|light]
  tuimark preview  FILE [--cols 80] [--rows 24] [--data FILE.json] [--watch] [--theme dark|light]
                        [--color truecolor|256|16|none]
  tuimark play     FILE [--cols 80] [--rows 24] [--data FILE.json] [--theme dark|light]
                        [--input STEPS | --script FILE.ndjson]
                        [--format text|json] [--cells] [--styles] [--frames] [--strict]
  tuimark fmt      FILE [--write] [--check]
  tuimark ir       FILE                       print the source IR as JSON
  tuimark agents   [--repo | --project]       print AGENTS.md generated from the catalog
                                               (--project: the briefing tuimark new writes)
  tuimark catalog                             print the closed vocabulary as JSON
  tuimark new      NAME [--go | --ts]         create a project: app.tui, theme.tcss, sample.json, AGENTS.md
  tuimark test     [DIR] [--update] [--allow-breaking]
                                               check dump goldens under DIR (default testdata/golden)
  tuimark inspect  FILE (--at X,Y | --id ID) [--cols 80] [--rows 24] [--data FILE.json]
                        [--theme dark|light] [--strict] [--json]
                                               explain one node: path, classes, pseudo-classes, styles
  tuimark run      FILE [--data FILE.json] [--theme dark|light] [--events FILE.ndjson]
                        [--mock FILE.json] [--strip]
                                               run in the terminal: F12 shows the events, edits reload
  tuimark host     FILE [--data FILE.json] [--theme dark|light] [--reply-timeout 5s]
                                               run in the terminal for a parent program (fd 3 in, fd 4 out)
  tuimark mcp                                 a Model Context Protocol server on stdin/stdout
  tuimark lsp                                 a Language Server Protocol server on stdin/stdout
  tuimark version

exit codes: 0 ok, 1 I/O or crash, 2 validation errors
```

## Commands [#commands]

| Command | What it does | Guide |
|---|---|---|
| `dump` | Renders one frame: the grid, every node's geometry, and the diagnostics. Text by default, `--format json` for agents. | [Dumps and tools](/guide/tools#dump) |
| `validate` | Checks a document without printing a frame. Lays it out at 40, 80, and 120 columns to find layout and bind problems. | [Getting started](/guide/getting-started#check-it) |
| `preview` | The text dump, plus the frame painted in ANSI colors when stdout is a terminal. `--watch` re-renders on save. | [Getting started](/guide/getting-started#look-at-it) |
| `play` | Replays keys, typing, pastes, clicks, and store changes with no terminal, and prints the final frame plus every action that fired. | [Dumps and tools](/guide/tools#play) |
| `inspect` | Explains one cell or node: its layout path, classes, pseudo-classes, and which rule set each property. | [Dumps and tools](/guide/tools#inspect) |
| `fmt` | The canonical formatter. `--check` exits 2 when a file is not formatted. | [Dumps and tools](/guide/tools#fmt) |
| `ir` | Prints the parsed document as JSON, before the stylesheet cascade. | [Dumps and tools](/guide/tools#ir) |
| `test` | Compares dumps with the goldens a manifest lists; `--update` rewrites them. | [Testing](/guide/testing#golden-dumps) |
| `agents` | Prints the `AGENTS.md` briefing, generated from the runtime's own catalogs. `--project` prints the briefing `new` writes into a project. | [Use Tuimark with AI agents](/guide/agents) |
| `catalog` | Prints the closed vocabulary (tags, attributes, properties, keys, actions, diagnostic codes) as JSON, each item with the document version that accepts it. | [Dumps and tools](/guide/tools#catalog) |
| `new` | Creates a project: `app.tui`, `theme.tcss`, `sample.json`, and `AGENTS.md`; `--go` or `--ts` adds the program that hosts it. | [Dumps and tools](/guide/tools#new) |
| `run` | Runs a document in the terminal with no host program: an event strip (`F12`), an `--events` log, `--mock` store writes, and reload on save. | [Running a document](/guide/run) |
| `version` | Prints the version. | |

## Exit codes [#exit-codes]

| Code | Meaning |
|---|---|
| `0` | ok |
| `1` | usage error, I/O error, or crash; nothing useful on stdout |
| `2` | the document has an error-severity diagnostic (`dump`, `validate`, `play`, `inspect`, `ir`), a file is not formatted (`fmt --check`), or a golden does not match (`test`) |

`run` exits `0` when the session quits or its input ends, and 128 + the signal number when a stop signal ends it.

`--cols` and `--rows` take 1 to 1000. `dump`, `validate`, `play`, `inspect`, `ir`, `fmt`, and `test` never read `TUIMARK_*` environment variables, so their output never depends on the machine they run on.