> ## Documentation Index
> Fetch the complete documentation index at: https://invariant-cad.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"system"}
invariantcad validate model.invariantcad.json
```

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

## Inspect

```bash theme={"system"}
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

```bash theme={"system"}
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

```bash theme={"system"}
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:

```json theme={"system"}
{
  "width": 120,
  "draftAngle": 0.03490658503988659
}
```

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

```bash theme={"system"}
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.