Skip to main content
The invariantcad binary operates on serialized design documents. It is useful for CI, build pipelines, and verifying documents produced elsewhere.

Validate

Parses and validates the frozen document grammar without evaluating geometry. Success prints the document version and name. Since 0.2.0, control characters, Unicode line and paragraph separators, and bidirectional embedding, override, and isolate controls in the name are printed as \uXXXX escapes, so an untrusted document cannot drive the terminal or forge extra output lines. The 0.1.1 CLI printed the name verbatim.

Inspect

Prints JSON measurements for every selected output, including geometric properties, triangle count, principal inertia, radii of gyration, and physical properties where the output supplies density. genus is a nonnegative exact integer when the selected kernel/result supports it and JSON null otherwise; the CLI never substitutes zero for unsupported topology. Add --output name to inspect only one output.

Bill of materials

The selected output must be a part or assembly. Output JSON includes the BOM, mass-completeness fields, and non-fatal BOM diagnostics.

Export

Supported --format values:
  • stl
  • stl-ascii
  • obj
  • step
  • brep
  • brep-binary
If --format is omitted, the destination extension selects the format, ignoring case: .obj writes OBJ, .step and .stp write STEP, and .brep and .brp write text BREP. Any other extension, or none, writes binary STL. Exact formats (step, brep, brep-binary) default the kernel to OCCT, while mesh formats default to Manifold unless --kernel is explicit. Assembly outputs export only as stl, stl-ascii, or obj; an exact format fails with EXPORT_UNSUPPORTED, as does an exact format with --kernel manifold. --output names the output to export. A document with exactly one output may omit it. When the document has several outputs, export requires --output and otherwise fails with exit code 2 after validating the document and before initializing a kernel, instead of choosing one for you. Frozen v1-v6 documents may name an output with the empty string; select it with --output "" or --output=. Export failures, such as an unsupported format for the selected kernel or output, are written to stderr as diagnostics; a destination that cannot be written, such as one in a missing directory, prints a one-line Output file could not be written: ... reason. Both return exit code 1.
Requiring --output for multi-output documents and reporting export or write failures without a stack trace were added in 0.2.0. When --output was omitted, the 0.1.1 CLI silently exported only the first output in the parsed document’s outputs key order, which is sorted name order only for a canonically serialized document. It printed a JavaScript stack trace when export or writing failed.

Parameter overrides

--parameters points to a JSON object of finite base-unit values:
Inline --parameter overrides and the rule against mixing them with --parameters were added in 0.2.0. The 0.1.1 CLI accepted only --parameters values.json and silently ignored --parameter, so the model evaluated at its default and configured values without an error.
For one-off automation, repeat --parameter name=value instead:
Inline values use finite JSON-number syntax. The name is the exact stored parameter key, including keys preserved by directly evaluable frozen legacy documents that the current builder would not author. The assignment is split at its final =, so a stored key containing = remains addressable. If that key begins with -, use the attached form, such as --parameter=-legacy-key=5, so it is not parsed as another option. Lengths are millimetres, angles are radians, mass density is kg/mm³, and scalars are unitless. Choose either --parameters or one or more --parameter options. Supplying both is a usage error instead of creating an implicit file-versus-command-line precedence rule. Runtime overrides take precedence over the selected named configuration and the document defaults.

Input files

These input-file checks were added in 0.2.0. The 0.1.1 CLI read whole files without them and reported a missing or unreadable document or parameter file with a JavaScript stack trace.
Document and parameter files are limited to the default maxDocumentBytes ceiling of 64 MiB. The CLI rejects a larger file without buffering it, then decodes the bytes as strict UTF-8: malformed sequences are errors instead of replacement characters, and a leading byte-order mark is not stripped, so JSON parsing rejects it. Documents go through parseDocument, and a parameter file that repeats a member name, including an escape-equivalent spelling, is rejected instead of silently keeping the last value. These failures, and a missing or unreadable file, write a one-line reason to stderr and return exit code 1.

Strict argument handling

Fail-closed argument handling was added in 0.2.0. The 0.1.1 CLI ignored unknown options and extra positional arguments instead of returning exit code 2, so a misspelled option silently had no effect.
Options are command-specific. Unknown or inapplicable options, extra positional arguments, missing or empty values, malformed inline parameters, and duplicate single-value options fail before document reading, kernel initialization, evaluation, or export. These failures write the reason and usage text to stderr and return exit code 2; the CLI never silently ignores a misspelled option. --output is the one option that accepts an empty value, because frozen v1-v6 output names are arbitrary strings; an empty name that the document does not define fails during evaluation with OUTPUT_MISSING and exit code 1. Command-scoped help validates any supplied option values without requiring or reading a document. For evaluation commands, a parameter file is read and validated before the selected geometry kernel is initialized.

Exit codes

Diagnostics are written to stderr as SEVERITY CODE path: message. Since 0.2.0, control characters and the other terminal-unsafe characters described under Validate are escaped as \uXXXX in paths and messages. The same characters inside inspect and bom JSON strings are written as \uXXXX escapes, so the output still parses to the same values; the 0.1.1 CLI escaped only the controls that JSON.stringify escapes. Machine integrations should prefer the TypeScript API when they need complete structured diagnostic details rather than parsing CLI text.