figcraft/docs/cli.md

# figcraft-cli

FigCraft without a window: inspect, export, convert and render documents, run command scripts, list
commands, serve MCP and measure performance. Build it with
`cargo build --release -p figcraft-cli` (binary `target/release/figcraft-cli`).

Bad arguments print usage and exit with code 2; failures exit with 1. The CLI never panics on input.

## Subcommands

### `info <file> [--json]`

Pages, node counts, top-level frames (id, type, name, size), style/variable/image counts. Repairs
of a damaged file and import warnings go to stderr as `note:` lines (`notes` with `--json`).

Every subcommand that reads a file also takes the public REST API file JSON (the response of
`GET /v1/files/:key` or of its nodes endpoint, written to a `.json` file): it is imported on the fly.
Image fills come from `images/<imageRef>.png` (or `.jpg`, …) next to the JSON when present, else a
grey placeholder.

```text
$ figcraft-cli info app.figcraft
app.figcraft — App (412 nodes, 6 styles, 12 variables, 3 images)
page 1 "Screens": 380 nodes, 4 top-level
  2 FRAME "Home" 393.0×852.0
  …
```

### `export <file> -o <out> [--format png|jpg|svg|webp|pdf] [--scale N] [--page NAME] [--node ID|NAME] [--bleed LENGTH] [--crop-marks] [--bleed-marks] [--cmyk]`

- `<out>` is a directory: one file per top-level frame of the page (default the first page), named
  after the frame (`Home.png`, `Settings.png`…); with no frames, one file per top-level layer.
- `<out>` has an image extension: one file with the given `--node`, or the whole page composited.
- `--node` takes a layer id (`12` or `0:12`) or a layer name.
- The format comes from `--format`, else `<out>`'s extension, else png. `--scale` (default 1, max 64)
  applies to raster formats.
- A `.pdf` `<out>` without `--node` holds the page's top-level frames, one PDF page each in reading
  order, each the frame's size in points (a page without frames goes on one page). Shapes, text
  and gradients stay vector, text is real (selectable, with subset fonts) and its links clickable;
  shadows and blurs are images.
- PDF print options: `--bleed` (points, or a length like `3mm` or `0.125in`, up to 2 in) grows each
  page by the bleed, which shows what lies past the frame's edge (its fills reach out to it, its
  children are clipped there instead); `--crop-marks` and `--bleed-marks` draw hairline marks
  outside the bleed; the page boxes are set (MediaBox the sheet, BleedBox, TrimBox the frame).
  `--cmyk` writes CMYK colour, images included, converted from sRGB with the naive formula
  `K = 1 − max(R, G, B)`, `C = (1 − R − K) / (1 − K)` (M and Y alike): DeviceCMYK without an
  output intent (no CMYK profile ships with FigCraft), so proof against your printer's profile.

```sh
figcraft-cli export app.figcraft -o exports/ --scale 2
figcraft-cli export app.figcraft -o hero.svg --node "Hero"
figcraft-cli export app.figcraft -o screens.pdf --page "Screens"
figcraft-cli export app.figcraft -o poster.pdf --node "Poster" --bleed 3mm --crop-marks --cmyk
```

### `convert <in> <out>`

By extension. Inputs: `.figcraft`, `.json` (FigCraft or REST API file JSON), `.svg` (an editable frame: groups,
shapes, text, gradients, masks and effects; `info` lists what it left out as `note:` lines), `.png/.jpg/.webp/.gif/.bmp`
(an image layer). Outputs: `.figcraft`, `.json` (FigCraft JSON, pretty-printed), `.svg`,
`.png/.jpg/.webp` (the current page rendered at 1x with its background), `.pdf` (the current page's
frames, one page each).

### `render <file> -o <out.png> [--scale N] [--page NAME]`

The whole page (default the first) with its background, as png, jpg or webp. Large pages are scaled
down to fit 16384 px.

### `run <script.json|script.jsonl> [--in <file>] [--out <file>]`

Runs commands in a headless session (a new document, or `--in`), printing one JSON line per step:

```text
{"command":"frame.create","ok":true,"result":{"id":2},"step":0}
```

A failing step prints `"ok": false` with the error and exits with code 1 (nothing is saved).
`--out` saves the result by extension like `convert`.

Script formats: a JSON array of `{"command": id, "params": {...}}`, an object
`{"commands": [...]}`, or JSON lines (one step per line; blank lines and `//` lines are skipped).

```json
[
  {"command": "frame.create", "params": {"preset": "iPhone 16", "x": 0, "y": 0, "name": "Home"}},
  {"command": "node.create", "params": {"type": "text", "parent": 2, "x": 24, "y": 64, "text": "Welcome", "props": {"fontSize": 32}}},
  {"command": "layout.add", "params": {"ids": [2], "direction": "vertical"}}
]
```

Ids are assigned in order (a new document's first page is 1, so the first layer is 2), which lets a
script refer to layers it created.

### `commands [--json] [--filter TEXT]`

Every command with its label, shortcut, undoable flag (`*`) and parameter docs; `--json` for
machines.

### `mcp [--attach PORT]`

Serve MCP on stdio: headless by default, or attached to a running app started with
`figcraft --control PORT`. See [mcp.md](mcp.md).

### `perf [--layers N[,N...]]`

Builds synthetic documents of each size (default `1000,10000` layers: screens with an auto layout
header, a card group, button instances and a grid of shapes and text) and prints a Markdown table of
the hot paths: build + normalise, save/load, 1440×900 renders at 100% and zoomed to fit, hit testing
and hover, single-layer edits through the engine (fill, move, text in auto layout, a main component
with all its instances), undo/redo, a drag preview frame, `normalize` after a one-node edit,
`document.inspect` and select-all + move. Use a release build for meaningful numbers;
`cargo xtask bench` runs it at 1k/10k/50k layers together with the UI frame benchmarks.