CLI Reference

Every subcommand and option of the poly command.

poly is a single binary. It needs no runtime and no packages. See Getting Started for how to install it.

poly --version
poly model.poly              # build is the default subcommand

Subcommands

Command	What it does	Geometry kernel
`build`	Export the model (STL / STEP / GLB / SVG / PNG)	yes
`check`	Validate syntax and semantics only	no (fast)
`info`	Report B-Rep facts (bbox, volume, solids, validity)	yes
`verify`	Everything needed to judge a result, in one report	yes
`section`	Cut with a plane and report the contours as numbers	yes
`diff`	Compare the B-Rep facts of two files	yes
`explain`	What a diagnostic code means and how to fix it	no
`dump-ast`	Dump the AST as JSON	no

Every subcommand accepts --json, which writes a machine-readable report to stdout instead of the human-facing output.

build

poly build <file> [options]
poly <file>                  # build may be omitted

The format follows the extension; --format overrides it.

Option	Description
`-o <path>`	Output file. Defaults to `<input>.stl`
`--format <fmt>`	`stl` / `step` / `glb` / `svg` / `png`
`-D, --define <k=v>`	Override a parameter. Repeatable
`--params-file <path>`	Read parameters from JSON (`-D` wins)
`--mesh-deflection <v>`	STL / glTF mesh precision. Default 0.1; larger is coarser
`--ascii-stl`	Write ASCII STL: about 6x larger, but diff-friendly
`--view <names>`	SVG / PNG viewpoints, comma-separated
`--view-size <px>`	SVG / PNG panel size. Default 240
`--no-hidden`	Omit occluded edges instead of dashing them
`--png-scale <n>`	PNG supersampling, 1-4. Default 2
`--trace`	Per-step source line, selection, volume and solid count
`--timing`	Stage times on stderr; adds an ms column to `--trace`
`--strict`	Treat warnings as errors (exit 3)
`-v, --verbose`	Print the result’s B-Rep facts
`--json`	Machine-readable report

Formats

Format	Contents	Use
`.stl`	Triangle mesh (binary by default)	3D printing, slicers
`.step`	B-Rep exchange format	Handing the model to another CAD
`.glb`	glTF binary, with `color` preserved per part	Web viewers
`.svg`	Line drawing with hidden-line removal	Drawings, checking dimensions
`.png`	The same drawing rasterised	Readers that take no SVG, READMEs, models that take raster input

.gltf is refused: OCCT writes only the binary container, so use .glb.

Viewpoints (SVG and PNG alike)

Seven names: front back top bottom left right iso. The default is the four-up front,top,right,iso; naming one draws a single panel.

poly build m.poly -o v.svg                          # four views
poly build m.poly -o v.png --view iso               # isometric only
poly build m.poly -o v.png --view front,top --view-size 400

+Z is up, front looks from the -Y side, and the isometric camera sits in (+X, -Y, +Z) — the same orientation SolidWorks and Fusion use, and the same one the live editor’s 3D view shows.

Overriding parameters

-D infers the type from how the value looks: 100 is an integer, 1.5 a float, true / false a boolean, anything else a string.

Precedence is -D > --params-file > the @param default.

poly build box.poly -D width=100 -D height=50
poly build box.poly --params-file presets/small.json -D width=120

check

Validates syntax and semantics without starting the geometry kernel. Skipping kernel startup makes it far faster, which suits an editor or a first CI gate.

poly check m.poly
poly check m.poly --json

info

Reports B-Rep facts only — for checking a shape by its numbers rather than by looking at it.

poly info m.poly
poly info m.poly -D width=120 --json

Prints the bounding box, volume, surface area, solid count, validity, and the face / edge / vertex counts.

verify

Everything needed to judge a result, in one report: diagnostics, a per-step trace, B-Rep facts, a fingerprint and the checks.

poly verify m.poly
poly verify m.poly -o out.stl --timing
poly verify m.poly --no-strict        # do not fail on warnings

By default a single warning fails the run with exit code 3.

section

Cuts the model with a plane and reports the contours. This gives numbers, not a picture.

poly section m.poly                      # default xz,yz through the bbox centre
poly section m.poly --plane Z=10         # an explicit position
poly section m.poly --plane xz,yz,Z=10   # several
poly section m.poly --plane Y=0 -o cut.svg

--plane takes xy / xz / yz, or an axis and a value such as Z=10. A plane given without a value cuts through the centre of the bounding box. -o also writes the contours as SVG, with path coordinates in millimetres.

diff

Compares the B-Rep of two files: fingerprint, volume, bounding box, topology.

poly diff before.poly after.poly
poly diff a.poly b.poly -D width=100    # same override applied to both

explain

Prints what a diagnostic code means and how to fix it.

poly explain                # list them
poly explain eval.error

dump-ast

Writes the AST as JSON, for tooling.

poly dump-ast m.poly --pretty

Exit codes

Code	Meaning
0	Success
1	I/O error (file unreadable, and so on)
2	Syntax error
3	Semantic error, or a warning under `--strict`
4	Export failed

About the implementation

The CLI is written in TypeScript and uses a WebAssembly build of OpenCASCADE as its geometry kernel. The single binary carries the kernel, so nothing is fetched at run time.

The Python implementation was frozen on 2026-09-01 and is no longer maintained. Where older documentation mentions flags such as --emit-python, they are not part of the current CLI.