Command-line interface

Validate, inspect, generate BOMs, and export InvariantCAD JSON documents.

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

Validate

invariantcad validate model.invariantcad.json

Parses and validates the frozen document grammar without evaluating geometry. Success prints the document version and name.

Inspect

invariantcad inspect model.json \
  --configuration manufacturing \
  --kernel occt \
  --parameter width=120 \
  --parameter draftAngle=0.03490658503988659

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

invariantcad bom assembly.json \
  --output machine \
  --configuration compact

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

Export

invariantcad export model.json \
  --output body \
  --to body.step \
  --kernel occt

Supported --format values:

• stl
• stl-ascii
• obj
• step
• brep
• brep-binary

If --format is omitted, .obj, .step/.stp, and .brep extensions are recognized; other destinations default to binary STL. Exact formats default the kernel to OCCT, while mesh formats default to Manifold unless --kernel is explicit.

Parameter overrides

--parameters points to a JSON object of finite base-unit values:

{
  "width": 120,
  "draftAngle": 0.03490658503988659
}

For one-off automation, repeat --parameter name=value instead:

invariantcad inspect model.json \
  --parameter width=120 \
  --parameter=draftAngle=0.03490658503988659

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.

Strict argument handling

Options are command-specific. Unknown or inapplicable options, extra positional arguments, missing 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. 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

Code	Meaning
0	Command completed successfully
1	Document, evaluation, BOM, or export operation failed
2	Command-line usage or argument error

Diagnostics are written to stderr as SEVERITY CODE path: message. Machine integrations should prefer the TypeScript API when they need complete structured diagnostic details rather than parsing CLI text.