Command line reference

The solid command follows the grammar:

solid <command> <path> [options]

where <path> is the python source file of the node to work on. A directory can be given instead, in which case its __init__.py is used — so solid develop root and solid develop root/__init__.py are equivalent. Commands must be run from the project root directory.

Run solid <command> -h to see the options of each command.

solid new

solid new <name>

Creates a new project directory <name> with a starting structure: a root node implementing a Solid2Node demo model, and a .gitignore for the build artifacts. Fails if <name> already exists. See the Quickstart.

solid develop

solid develop <path> [--web] [--web-dev] [--openscad]
                     [--debug-builder] [--debug-web] [--callback URL]

Runs everything needed to develop a project: monitors the filesystem, rebuilds the parts that changed, and serves a viewer that reloads automatically.

--web

Start a webserver at http://localhost:8000 to view the project in the browser. This is the default when no viewer option is given.

--openscad

Open the project in the OpenSCAD GUI instead. OpenSCAD reloads the generated code when it changes, except while animating.

--web-dev

For working on the web viewer itself: additionally start the frontend development server (a proxy to npm start in the viewer’s React app), so viewer code changes hot-reload too.

--debug-builder

Run the builder in the foreground so breakpoints work. Automatic reload is disabled in this mode.

--debug-web

Run the webserver in the foreground to support breakpoints in it.

--callback URL

In normal web mode, POST the exact URL (with no request body) after the initial complete build and every later complete rebuild. The callback is best effort: delivery failures are logged and never stop development. It cannot be combined with --openscad or --web-dev.

solid build

solid build <path>

Builds the node once using the same ordinary pipeline as solid develop, publishes the complete current model in the normal build directory, and exits. It starts neither a viewer nor a filesystem watcher. A missing resolved model prints a diagnostic and exits with status 66 (MODEL_NOT_FOUND); other build errors use a generic non-zero status. A failed later build leaves the last complete published artifacts in place.

solid test

solid test <path> [--failfast]

Builds the node at <path> and runs its tests — the test_* methods of the node itself (via TestCaseMixin) and of its companion test file, if one exists. See Test-driven CAD for how to write tests.

--failfast

Stop the test run on the first failure.

solid snapshot

solid snapshot <path> [options]

Renders the node to a PNG image using the OpenSCAD CLI, without opening any viewer. This gives a headless way to inspect a model — in CI, or for AI agents to visually check their work.

$ solid snapshot root -o front.png --viewall --autocenter
$ solid snapshot root --time 0.25 --imgsize 800x600 --projection ortho

-o, --output

Output file path. Default: snapshot.png.

--time

Animation time to render, between 0.0 and 1.0. Default: 0.0.

--camera

Camera specification in OpenSCAD format. Either gimbal (translate_x,y,z,rot_x,y,z,dist) or vector (eye_x,y,z,center_x,y,z).

--autocenter

Adjust the camera to look at the object’s center.

--viewall

Adjust the camera so the whole object fits in view.

--imgsize

Image dimensions as WxH. Default: 1920x1080.

--projection

perspective (default) or ortho.

--colorscheme

One of OpenSCAD’s color schemes (Cornfield, Metallic, Sunset, Starnight, BeforeDawn, Nature, DeepOcean, Solarized, Tomorrow, Tomorrow Night, Monotone). Default: Cornfield.

--render / --preview

Mutually exclusive. --render does a full render (OpenSCAD’s default: slower, accurate); --preview uses the ThrownTogether preview mode (faster, may show artifacts).

--view

Comma-separated view helpers: axes, crosshairs, edges, scales, wireframe.

solid export

solid export <path> [options]

Builds the node’s STL meshes and writes a static, self-contained directory that renders the model — animations included — in any browser, with no server-side code. See Embedding models in pages and docs for what the output contains and how to use it.

$ solid export root -o export
$ python -m http.server -d export   # view at http://localhost:8000

-o, --output

Output directory. Default: export.

--fps

Animation frames per second in the manifest. Default: 30.

--frames

Frames per animation cycle. Together with --fps this sets the cycle duration (default: 360 frames at 30 fps = 12 seconds).

--no-widget

Export only manifest.json and models/, without the viewer page and JS bundle. Useful when the viewer is supplied elsewhere — for example by the Sphinx extension at documentation build time.

Environment variables

SOLID_BUILD_DIR

Directory where generated .scad and .stl files are placed, relative to the project root. Default: _build.