# Check, preview and export with the CLI [Start here](https://pegmatite.dev/guide/start.md). Fetch this topic when you verify a model, read a check report, render a view or export a file from the command line. ## Workflow The npm package `pegmatite` needs Node.js 22 or newer. `--check` is the agent's main inspection tool: it builds the model and prints dimensions, part bounds and labelled positions as text. 1. Record what should be true: overall and per-part sizes, feature sizes, alignment, gaps, cutter depths. Label the base and every feature whose position matters, cutters included. Label a macro call or compound itself; its inner labels are private. 2. Run `npx --yes pegmatite --check --strict model.pegm`. Read stdout for the report and stderr for diagnostics; do not use `--quiet`. 3. Fix errors, warnings and mismatched spans, then recheck. Under `--strict` a warning fails the input and can suppress the report. 4. Render a view only for what the report cannot settle, such as a hole opening, a curve or appearance: `npx --yes pegmatite model.pegm -o model-top.png --view top`. Open the image. After a fix, rerun `--check`; rerender only if the visual question remains. 5. Export after the checks pass, and state what was verified, which views were inspected and what remains uncertain. A successful exit does not prove the design correct. An empty model passes a check with zero size and zero parts, but cannot be exported to 3MF or PNG. Without the CLI, say which checks are undone and offer the script for the [editor](https://pegmatite.dev/editor). For repeated use, `npm install pegmatite` and run `npx pegmatite …`. ## Options **Syntax:** **`npx pegmatite`** [_options_] _script_… There is no `check`, `render` or `export` subcommand. | Argument or option | Meaning | | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | | _script_… | One or more scripts; each writes a `.3mf` by default. | | `-` | Read UTF-8 script text from stdin; requires `-o`, even with `--check`. | | `-o`, `--output` _p_ | Output for a single input. `.3mf`, `.stl`, `.step`/`.stp` or `.png` picks the format. `-` writes binary 3MF to stdout. | | `--check` | Build at export quality without writing output; report dimensions and labelled volumes. | | `--strict` | Warnings fail; that input writes no output. | | `--slow` | Build slow steps, such as a shell needing a general computation; without it they are left out with a warning. | | `--quiet` | Suppress success summaries and check reports; diagnostics still print. | | `--view` _name_ | PNG view: `iso` (default), `front`, `back`, `left`, `right`, `top`, `bottom`. | | `--size` _pixels_ | Square PNG size, 64–2048; default 512. | | `-h`, `--help` | Show help. | | `--` | End options, so paths may begin with a dash. | Paths are relative to the working directory; output directories must exist. Without `-o`, the input's final extension becomes `.3mf`; an output with no extension is 3MF. Extensions are case-insensitive. PNG needs a named path. `--view` and `--size` require PNG output and cannot accompany `--check`. Several inputs run independently in order; a failure does not stop later ones, and generated outputs remain. Conflicting output paths and outputs that would overwrite an input are rejected. An existing output is replaced only after successful generation. ```sh npx pegmatite a.pegm b.pegm npx pegmatite model.pegm -o out/model.3mf printf 'cube 10\n' | npx pegmatite --check - -o - npx pegmatite model.pegm -o - > model.3mf ``` ## Reading the check report `--check` prints to stdout the input name, X × Y × Z size in millimeters and part count, then one row per labelled volume: slot size, span on each world axis, source line. ```pegm base: block 40 20 10 post: cylinder 6 20 cap: cylinder 12 6 ``` ```output model.pegm 40 × 20 × 36 mm, 1 part base: 40 × 20 × 10 x -20..20 y -10..10 z 0..10 line 1 post: 6 × 6 × 20 x -3..3 y -3..3 z 10..30 line 2 cap: 12 × 12 × 6 x -6..6 y -6..6 z 30..36 line 3 ``` Rows show the slot, the room used for placement and [measures](https://pegmatite.dev/guide/expressions.md), which can differ from the material. A `material` row follows when material bounds differ from the slot; a `slot` gets `no material`. Material is measured as that statement built it, before later booleans. A turned slot is reported as the box around it. Coordinates match the export: centered in X and Y, Z up. The summary uses up to six decimals, rows three. Labels in lists, patterns and parts appear in build order, one row per iteration. Labels inside compounds and macro bodies are private. With `part`, the report and diagnostics are grouped by part. Each part heading gives its material size and spans, then its labelled volumes; geometry before the first part is `Unnamed`. The exported part count reflects fusion and color splitting: disconnected pieces and different colors count separately even within one `part`. ### Spans as placement checks Above, the post's `z 10..30` starts at the base's top, `z 10`; its X and Y spans are centered in the base. The cap starts at `z 30` and the stack ends at `z 36`. That verifies the stacking without an image. - Compare each size and span with the specification. Equal span midpoints mean centered; equal min or max values mean aligned edges. Subtract spans for a gap or offset. - A through-cutter's span must cover the thickness it cuts. A cutter outside its target's bounds cannot reach it. Overlapping bounds are only a first check, especially for curves. - Read part bounds as well as the total. An unexpected part count can flag disconnected material, but deliberate parts and color splitting also change it. - Read the `material` row when actual extent matters. `no material` under a `slot` is deliberate empty space, not a missed cut. The negative-volume warning means a subtraction removed nothing from material already built in its construction context. It does not catch a positive feature that fails to touch another. Bounds cannot prove contact, wall thickness or a through-hole; use a targeted view when one of those matters. ## Previews PNG rendering needs no browser or GPU. It fits the whole model in an orthographic view with a transparent background and edge outlines. `iso` looks from front-right and above. Views use world directions: front is −Y, right is +X, top is +Z, whatever local frames the script used. ```sh npx pegmatite model.pegm -o model-front.png --view front --size 1024 ``` The PNG summary reports model dimensions, independent of view and size. A view with no visible area is an error. Larger images cost more time and memory. ## 3MF, STL and STEP 3MF uses millimeters, Z up, the model centered in X and Y with its base at Z = 0, and export-quality curves: finer than the interactive preview, while explicit polygon side counts stay. It keeps colors and parts. STL is binary with the same geometry and placement, triangles only: colors and part names are dropped and all bodies share one mesh. Prefer 3MF when the slicer accepts it. STEP keeps exact curved surfaces where available; unsupported surfaces become flat facets, and very large faceted conversions are refused. Each body carries its part name, or the script file name, and its color. STEP needs the optional OpenCascade package in the matching version: ```sh npx --yes -p pegmatite -p replicad-opencascadejs@1.1.0 pegmatite model.pegm -o model.step ``` Or install `pegmatite` and `replicad-opencascadejs@1.1.0` in one project. Missing or incompatible OpenCascade is a setup error before compilation. `--check` with a `.step` output needs no OpenCascade and writes nothing. ## Fonts `font` can name a local `.ttf`, `.otf`, `.woff`, `.woff2` or `.ttc` file, relative to the script's directory, or the working directory for stdin. Files are limited to 10 MB; a collection uses its first font. A missing file is an error. Google Fonts names and HTTPS URLs need network access. See [text](https://pegmatite.dev/guide/text.md) for the syntax. ## Diagnostics and exit codes Errors and warnings go to stderr with source path, line and column (1-based) when known. Ordinary warnings allow export; `--strict` fails them. A shell needing a slow general computation is left out with a warning; `--slow` builds it, which can take minutes. Success summaries also go to stderr, leaving stdout for check reports, help or binary 3MF. `--quiet` never hides diagnostics. There is no JSON report. | Exit code | Meaning | | --------- | ---------------------------------------------------------- | | `0` | All inputs succeeded, with warnings allowed unless strict. | | `1` | Script or model errors, or warnings under `--strict`. | | `2` | Invalid options, input/output, or setup failure. | With mixed failures, `2` wins.