The shapescript command-line tool is available as a separate download from the ShapeScript GitHub releases page, and is available for both macOS and Linux. It can check .shape and .csg files from Terminal, report errors and warnings, and export models or images without opening a document window. This makes it useful for scripting workflows, bulk-exporting multiple files, and integrating ShapeScript into automated build pipelines.
On Mac, exporting from the command-line tool requires an unlocked copy of the ShapeScript Mac app to be installed on the same machine. You can still use the command-line tool to check files and report errors without unlocking Export.
You can download the latest ShapeScript CLI for Mac or Linux from the release page, or install it to $HOME/.local/bin by running this command in Terminal:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/nicklockwood/ShapeScript/HEAD/Viewer/CLI/install.sh)"
The installer downloads the correct prebuilt release for your platform and installs shapescript to $HOME/.local/bin. The prebuilt Linux binary is for x86_64 Ubuntu. Other Linux distributions may work, but Ubuntu is the supported target for the prebuilt download.
If shapescript is not found after installation, add $HOME/.local/bin to your shell path. For the default macOS shell use:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
For Bash or Linux:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
To check the installed version, open a new Terminal window after changing your shell path, then run:
shapescript --version
Run shapescript info with a .shape or .csg file to display scene info and report any errors:
shapescript info myfile.shape
To export the file, use shapescript export with an output path:
shapescript export myfile.shape --output myfile.stl
OpenSCAD CSG files can be passed directly to check, info, and export:
shapescript check Part.csg
shapescript info Part.csg
shapescript export Part.csg --output Part.stl
Run shapescript --help to see the current command-line usage and available subcommands. For export-specific options, run shapescript help export.
See Command-Line Export for more information.
If a .shape file declares script options, you can pass values for them after a -- separator. Options are written as --name value pairs:
shapescript check myfile.shape -- --radius 2 --color '#ff0000'
The same syntax works with info and export:
shapescript info myfile.shape -- --label "Test Part"
shapescript export myfile.shape --output myfile.stl -- --radius 2
Values are interpreted using the type implied by the script option’s default value. Simple strings can be passed directly:
shapescript check myfile.shape -- --label "Left Bracket"
For vector, color, rotation, or calculated values, use ShapeScript expression syntax and quote the value so your shell passes it as a single argument:
shapescript check myfile.shape -- --position "1 0 0"
shapescript check myfile.shape -- --color "(1 0 0)"
shapescript check myfile.shape -- --radius "1 + 2"
Hex colors should normally be quoted, because # begins a comment in many shells:
shapescript check myfile.shape -- --color '#ff0000'
You can also build the command-line tool from source. This builds the feature-limited open source version used for the Linux build, not the full macOS version described above. It supports STL models and BMP images. Images are rendered using a simplified software renderer that may not capture all the features of your scene in full fidelity.
To build directly with Swift Package Manager, install the latest Swift toolchain, then run:
git clone https://github.com/nicklockwood/ShapeScript
cd ShapeScript
swift build -c release
Alternatively, Mint users can install the latest version with:
mint install nicklockwood/ShapeScript
Mint installs command-line tools to $HOME/.mint/bin, so make sure that directory is included in your shell path if shapescript is not found after installation.