CLI Reference

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

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.

Formats

.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. A broken assert in the model also exits with 3; the trace and the summary are still printed, with each assert ... row marked pass or FAIL (build writes no file in that case).

measure

Evaluates one expression against the built model. The expression is written in the model’s own language and sees every top-level variable.

poly measure m.poly 'lid.bbox.z'
poly measure m.poly 'clear(lid, body)'
poly measure m.poly '(body | faces >Z).area'
poly measure m.poly 'g.volume' --json      # {"value": 15552, ...}

The properties (volume area solids faces edges verts bbox valid) are listed under “Measuring and checking” in the language reference. A check worth keeping goes into the file as an assert.

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, centre of mass. The centre is what notices a feature that moved without changing size (a pocket slid across a face).

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

ops

Prints every operation’s arguments, named arguments and contexts straight from the implementation, so unlike a hand-written table it cannot drift.

poly ops                  # one line per operation: signature and description
poly ops thread           # one operation in full: arguments, named arguments, contexts before and after
poly ops --json           # the same as JSON

Named arguments are checked against this table: a key the operation does not read (chamfar:true, or dir: on a box) stops poly check with arg.unknown-option and a suggestion when a listed key is close. It used to be ignored silently.

explain

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

poly explain                # list them
poly explain eval.error

live

Puts the file’s source in a URL and opens it in the Live editor in your browser. Use it to show a model to someone with nothing to install, or to try its parameters on sliders.

poly live m.poly            # open it in the browser (the URL is printed too)
poly live m.poly --print    # print the URL without opening it

The URL is https://live.objhub.org/?code=<URL-encoded source>. The source travels in the URL, so sharing the link shares the source.

The editor runs in the browser and cannot read your files, so imports are inlined first: the defs and assignments of each imported file (what an import actually brings in) are copied, as written, where its import line was. An import that cannot be found stops it with live.import.

It warns with live.too-long when the URL is longer than 16 KB, which the server may refuse.

If no browser can be started (over SSH, for instance) it reports live.no-browser and exits 1. The URL is still printed; open it yourself.

dump-ast

Writes the AST as JSON, for tooling.

poly dump-ast m.poly --pretty

Exit codes

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.