Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
cq-cli is a Command Line Interface for executing CadQuery scripts and converting their output to another format. It uses a plugin system where "codecs" can be placed in the cqcodecs directory and will be automatically loaded and used if a user selects that codec from the command line.
Input and output files can be specified via arguments, but cq-cli also supports stdin, stdout, and stderr streams so that it can be used in a pipeline.
Requires Python 3.11 or later. Linux, macOS, and Windows are supported, though some features may behave differently on Windows.
uv is the recommended way to install and run cq-cli. It handles Python version management and virtual environments automatically.
uv venv --python 3.11 source .venv/bin/activate # Windows: .venv\Scripts\activate uv sync
Once complete, run cq-cli with:
cq-cli --help
It is strongly recommended to use a Python virtual environment when installing via pip.
To install the latest release from PyPI, use the following command:
pip install cadquery-cli
Note: There was a naming collision on PyPI which required the package name to be cadquery-cli rather than cq-cli. The command name stays the same after installation though.
To install the latest development version instead of the stable release, use the following command:
pip install git+https://github.com/CadQuery/cq-cli.git
Once the installation is complete, the CLI can be invoked as:
cq-cli --help
or:
python -m cq_cli.main --help
cq-cli [-h] [--codec CODEC] [--infile INFILE] [--outfile OUTFILE]
[--errfile ERRFILE] [--params PARAMS] [--outputopts OPTS]
[--getparams GETPARAMS] [--validate VALIDATE] [--expression EXPRESSION]
Command line utility for converting CadQuery script output to various output formats.
| Argument | Description |
|---|---|
| -h, --help | Show help message and exit |
| --codec CODEC | The codec to use for conversion (e.g. step, stl, svg, dxf, glb, gltf, threejs). Can be omitted if --outfile has a recognised extension. Multiple codecs can be specified separated by ; — must match the number of --outfile entries. |
| --infile INFILE | The input CadQuery script (.py) or FreeCAD file (.fcstd). Reads from stdin if omitted. |
| --outfile OUTFILE | File to write the converted output to. Prints to stdout if omitted. Multiple output files can be specified separated by ;. |
| --errfile ERRFILE | File to write errors to. Prints to stderr if omitted. |
| --params PARAMS | Parameters to pass to the script. Accepts: a JSON file path, a JSON string ({"width":10}), or a colon/semicolon delimited string (width:10;height:5;). |
| --outputopts OPTS | Codec-specific options as a colon/semicolon delimited string. e.g. width:100;height:200; |
| --getparams GETPARAMS | Analyse the script and write parameter metadata as JSON. Pass a file path to write to a file, or true to print to stdout. |
| --validate VALIDATE | Set to true to validate the script without producing output. |
| --expression EXPRESSION | A Python expression to evaluate and render (e.g. my_shape(x=5)). Useful for rendering a specific part from a file that contains multiple functions. |
- Find out what codecs are available.
cq-cli --codec help
- Validate a CadQuery script.
cq-cli --validate true --infile /input/path/script.py
- Convert a CadQuery script to STEP format and output to stdout.
cq-cli --codec step --infile /input/path/script.py
- Convert a CadQuery script to STEP format and write to a file.
cq-cli --codec step --infile /input/path/script.py --outfile /output/path/newfile.step
- Convert a CadQuery script and write any errors to a separate file.
cq-cli --codec step --infile /input/path/script.py --errfile /error/path/error.txt
- Convert a CadQuery script using stdin and stdout streams. This example counts the lines in the resulting STEP output.
cat /input/path/script.py | cq-cli --codec step | wc -l
- Let cq-cli infer the codec from the output file extension.
cq-cli --infile /input/path/script.py --outfile /output/path/newfile.stl
- Convert to multiple output formats in a single invocation.
cq-cli --infile /input/path/script.py --outfile /output/path/model.step;/output/path/model.stl
- Convert a CadQuery script to SVG, passing output options to influence the resulting image.
cq-cli --codec svg --infile /input/path/script.py --outfile /output/path/newfile.svg --outputopts "width:100;height:100;marginLeft:12;marginTop:12;showAxes:False;projectionDir:(0.5,0.5,0.5);strokeWidth:0.25;strokeColor:(255,0,0);hiddenColor:(0,0,255);showHidden:True;"
- Convert a CadQuery script to STL, adjusting mesh quality. Explanation of linear vs angular deflection can be found here.
cq-cli --codec stl --infile /input/path/script.py --outfile /output/path/script.stl --outputopts "linearDeflection:0.3;angularDeflection:0.3"
- Extract parameter information from a script. Omit the file path to print JSON to stdout.
cq-cli --getparams /output/path/params.json --infile /input/path/script.py
- Pass JSON parameter information from a file to the script.
cq-cli --codec stl --infile /input/path/script.py --outfile /output/path/output.stl --params /parameter/path/parameters.json
- Pass JSON parameter data as a string on the command line.
cq-cli --codec stl --infile /input/path/script.py --params "{\"width\":10}"
- Pass parameters as a colon/semicolon delimited string.
cq-cli --codec stl --infile /input/path/script.py --outfile test.stl --params "width:2;centered:True"
- Render a specific function from a file using --expression.
cq-cli --codec step --infile /input/path/script.py --outfile /output/path/part.step --expression "my_part(x=5)"
The recommended way to set up a development environment is with uv.
git clone https://github.com/CadQuery/cq-cli.git cd cq-cli uv venv --python 3.11 source .venv/bin/activate # Windows: .venv\Scripts\activate uv sync --extra dev
Alternatively, using pip:
git clone https://github.com/CadQuery/cq-cli.git cd cq-cli python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e .[dev]
Run the test suite:
pytest -v --ignore=tests/test_freecad.py
The codec plugin system is based on naming conventions so that cq-cli knows what codec options to accept from the user. When adding a codec, place it in the cqcodecs directory and follow the naming convention cq_codec_[your codec name].py. The your codec name part of the filename will automatically be used as the codec name specified by the user.
A good starting point is cqcodecs/cq_codec_step.py, which shows a simple codec implementation that relies on CadQuery to do the heavy lifting. At minimum, your codec needs a convert function that accepts a CQGI BuildResult object and returns a string or bytes representing the converted model. If the codec writes the output file directly, return None and cq-cli will assume the output was written to disk.
A test is required when adding a codec to cq-cli. Add a file named test_[your codec name]_codec.py in the tests directory. tests/test_step_codec.py is a good template.
| Code | Meaning |
|---|---|
| 0 | Operation completed successfully. |
| 1 | The CadQuery script could not be read from --infile. |
| 2 | Usage error — incorrect or insufficient arguments. |
| 3 | No valid codec was provided or could be inferred. |
| 100 | Error while running the CadQuery script (build error, possibly from OCCT). |
| 200 | Error while running the conversion codec. |
This repository has five GitHub Actions workflows in `.github/workflows`:
CI/CD
- lint.yml\: Runs Black formatting checks (currently on Python 3.13).
- tests.yml\: Runs the main test suite with pytest (currently on Python 3.11).
- test\_freecad.yml\: Runs FreeCAD-specific integration tests in a conda environment.
Builds per OS - WIP
- pyinstaller.yml\: Manually triggered PyInstaller builds for Linux, macOS, and Windows.
- pyinstaller-builds-actions.yml\: Alternate/manual conda-based cross-platform PyInstaller build workflow.