# Satzstrom CLI Reference

The local Satzstrom CLI creates projects, runs the live preview, checks layouts, inspects pages, and writes PDFs with explicit inputs.

```sh
satzstrom <command> [options]
satzstrom --version
satzstrom --help
```

Every document command requires an exact `.tsx` `documentPath`. External component props are loaded only from an inline JSON object through `--args` or an explicit JSON file through `--data`. These options are mutually exclusive. The document module validates them with its exported named Zod object schema.

Common document options are:

| Option         | Type         | Meaning                                              |
| -------------- | ------------ | ---------------------------------------------------- |
| `documentPath` | path         | Required exact `.tsx` document file.                 |
| `--args`       | JSON object  | Inline props; alternative to `--data`.               |
| `--data`       | path         | JSON file containing props; alternative to `--args`. |
| `--timeout`    | milliseconds | Positive render time limit; defaults to 30000.       |

## init

```sh
satzstrom init <directoryPath>
```

Creates a parameterless starter document in a new project directory and installs its npm dependencies. The result is immediately ready for `satzstrom dev <directoryPath>/document.tsx`.

## add

```sh
satzstrom add <documentPath>
```

Creates exactly one `.tsx` document in a prepared TypeScript project. The parent directory exists, and the nearest project has `package.json`, `tsconfig.json`, and a declared `@satzstrom/primitives` dependency. `add` changes none of those files.

## dev

```sh
satzstrom dev <documentPath> [--args <json> | --data <dataPath>] [--port 0] [--timeout 30000]
```

Starts the paginated live preview on `127.0.0.1` and refreshes when relevant files change. `--port` accepts 0 through 65535; 0 chooses a free port.

## check

```sh
satzstrom check <documentPath> [--args <json> | --data <dataPath>]
  [--strict] [--debug-layout debug.pdf] [--overwrite]
  [--pdfa 2a] [--pdfua 1] [--timeout 30000]
```

Checks arguments, pagination, and diagnostics without writing the final PDF.

| Option                  | Meaning                                    |
| ----------------------- | ------------------------------------------ |
| `--strict`              | Treats layout warnings as errors.          |
| `--debug-layout <path>` | Also writes a PDF with layout markers.     |
| `--overwrite`           | Replaces an existing debug PDF.            |
| `--pdfa 2a`             | Creates and verifies PDF/A-2a constraints. |
| `--pdfua 1`             | Creates and verifies PDF/UA-1 constraints. |

## inspect

```sh
satzstrom inspect <documentPath> [--args <json> | --data <dataPath>]
  [--start-page 0] [--end-page -1] --images|--text
  [--out <directoryPath>] [--scale 1] [--debug] [--timeout 30000]
```

Returns selected pages as PNG files, visible text, or both. At least one of `--images` and `--text` is required.

| Option         | Meaning                                                                                |
| -------------- | -------------------------------------------------------------------------------------- |
| `--start-page` | First page of an inclusive, one-based range. `0` with end page `-1` selects all pages. |
| `--end-page`   | Last page of the inclusive range. `-1` with start page `0` selects all pages.          |
| `--images`     | Writes PNGs and returns their absolute paths.                                          |
| `--text`       | Returns visible text for each page.                                                    |
| `--out`        | PNG output directory.                                                                  |
| `--scale`      | PNG pixel density, greater than 0 and no greater than 4.                               |
| `--debug`      | Adds layout markers to PNGs.                                                           |

The command returns compact JSON.

## render

```sh
satzstrom render <documentPath> [--args <json> | --data <dataPath>]
  [--out <outputPath>] [--overwrite] [--strict]
  [--debug-layout debug.pdf] [--pdfa 2a] [--pdfua 1] [--timeout 30000]
```

Paginates the document and writes the final PDF. Without `--out`, the output is placed beside the document with its filename and a `.pdf` extension. `--overwrite` replaces existing output files. `--strict`, `--debug-layout`, `--pdfa 2a`, and `--pdfua 1` have the meanings described for `check`.

## setup, doctor, and mcp

`satzstrom setup` downloads the pinned Chromium version and verifies its integrity.

`satzstrom doctor` checks the CLI runtime, Chromium, PDF engine, and project dependencies.

`satzstrom mcp` starts the local stdio MCP server with `init`, `add`, `check`, `inspect`, and `render`.

## Markdown navigation

- [Primitives reference](/docs/primitives.md)
- [MCP reference](/docs/mcp.md)
- [Quickstart](/quickstart.md)
- [Complete docs index](/docs/llms.txt)
- [Complete Markdown index](/llms.txt)