zoo-kcl-check-cli

Local checks for Zoo / KittyCAD KCL: formatting, syntax, style, execution errors, and sketch constraints. Works offline, without a Zoo account or API tokens.

Execution uses a mock CAD engine. A successful check does not validate 3D geometry — verify it in Zoo.

Installation

pipx install zoo-kcl-check-cli

Also available via pip install zoo-kcl-check-cli or uv tool install zoo-kcl-check-cli. Requires Python 3.11–3.14. Package on PyPI.

Usage

kcl-check lint main.kcl
kcl-check execute main.kcl
kcl-check sketches main.kcl
kcl-check format main.kcl --write

You can pass a directory instead of a file:

kcl-check lint .
kcl-check execute .
kcl-check sketches .
kcl-check format . --check

lint and format process .kcl files recursively, skipping symbolic links. execute and sketches run default_file from project.toml or main.kcl. Imports of neighboring KCL files are supported.

Warnings also cause failure. The sketches command fails for under-constrained or conflicting sketches and incomplete reports.

Use kcl-check COMMAND --help for command options.

Output

Output is text by default. Diagnostics go to stderr; results and reports go to stdout. Engine errors include a code excerpt and a pointer to the problem when that information is available.

For scripts, CI, and coding agents:

kcl-check execute main.kcl --json

--json returns one object in stdout, including on failure. Main fields: ok, exit_code, diagnostics, sketches, formatting. See the result contract for the full format.

All commands support --timeout SECONDS; the default is 60 seconds for the entire command.

Agent skills

• kcl-modeling — modeling rules and KCL techniques.
• kcl-check — CLI installation, running checks, and interpreting results.

npx skills add gavroman/zoo-kcl-check --skill kcl-modeling --skill kcl-check

Development

Setup, tests, and builds. Report bugs and suggestions in GitHub Issues.

License

MIT.