use-openscad

Use OpenSCAD

Design parametric 3D and 2D parts in OpenSCAD and compile them to fabrication outputs with the openscad CLI. OpenSCAD is a functional code-based CAD language — modules and functions, CSG booleans, extrusion — ideal for an agent to write and iterate.

Process

1. Understand what the user wants (a printable part, a laser-cut plate, a preview image, a mesh conversion) and pick the target format (STL/3MF/AMF for 3D printing, DXF/SVG for 2D cutting, PNG for preview).
2. Locate and verify the binary (see "Locating the binary"). Run openscad_run --version first to confirm it works.
3. Author the .scad model using references/language.md for syntax. Make dimensions -D variables when the user wants parametric control from the command line.
4. Compile with the right flags from references/cli.md. Use references/workflows.md for end-to-end recipes and references/design.md for printability rules.
5. After STL/3MF export, scan stderr for manifold warnings (see CRITICAL rules) before declaring success.

CRITICAL operating rules

• Mesh exports (STL/3MF/AMF/DXF/SVG) always get full CGAL geometry — --render is NOT needed for them. --render only affects PNG image export (without it, PNG uses OpenCSG preview). A plain openscad -o out.stl model.scad produces a complete mesh. For STL, explicitly pass --export-format binstl (ASCII is the current default; binary is the planned future default). After export, scan stderr for manifold warnings — see below.
• macOS binary is not on PATH. It lives at /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD. On Linux try openscad or openscad-nightly; on Windows invoke openscad.com (the wrapper, not openscad.exe). On remote servers, use the Docker image (see hardware/scripts/docker/openscad/). MUST confirm with openscad_run --version before building a pipeline.
• Exit codes are not officially documented. Empirically non-zero on compile/parse error, zero on success even with warnings; --hardwarnings makes the first warning fatal. Do NOT assume — for CI gating, run with --hardwarnings and treat any non-zero exit as failure. When unsure of a flag, run openscad --help and read the actual list.
• Variables are immutable within a scope. Reassigning in the same scope replaces-at-origin (the first assignment is never executed, a warning is emitted); braces create inner scopes that do not leak outward. Use is_undef(x), not x == undef. -D var=val constants from the CLI override top-level program values.
• use libraries, do not include them. include <lib.scad> is literal copy-paste that runs top-level geometry and confuses error line numbers; use <lib.scad> suppresses top-level geometry and exposes only functions/modules. Use use for any library file.
• String -D values need shell quoting. -D 'mode="parts"' (bash) — the inner quotes are part of the OpenSCAD expression. Numeric -D w=60 needs no quotes.
• Scan stderr after mesh export. Capture 2>&1 and grep for manifold, self-intersect, degenerate, warning — OpenSCAD prints mesh problems to stderr even when the exit code is zero. See references/workflows.md.

Command map

User wants	Flags	Reference
STL for 3D printing	--export-format binstl -o out.stl	references/cli.md
3MF / AMF	-o out.3mf	references/cli.md
2D DXF / SVG (laser cut)	-o out.dxf	references/cli.md
Preview PNG	--preview --imgsize W,H --viewall --autocenter (--render for accurate non-preview)	references/cli.md
Parametric variants	-D var=val (repeatable)	references/cli.md
Batch render	shell loop over -D values	references/workflows.md
Mesh conversion (STL→3MF)	import() in a re-export .scad	references/workflows.md
Language syntax	modules, functions, CSG, extrusion	references/language.md
Printability rules	walls, overhangs, clearance	references/design.md

Locating the binary

# Resolve the OpenSCAD binary — local binary or Docker container
__openscad_resolve() {
  # 1. macOS .app bundle
  local mac="/Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD"
  if [[ -x "$mac" ]]; then echo "local:$mac"; return; fi
  # 2. PATH
  if command -v openscad &>/dev/null; then echo "local:openscad"; return; fi
  if command -v openscad-nightly &>/dev/null; then echo "local:openscad-nightly"; return; fi
  # 3. Docker (image must exist locally)
  if command -v docker &>/dev/null; then
    local img="${OPENSCAD_DOCKER_IMAGE:-openscad-cli}"
    if docker image inspect "$img" &>/dev/null 2>&1; then
      echo "docker:$img"
      return
    fi
  fi
  echo ""
}

OPENSCAD_TARGET="$(__openscad_resolve)"
if [[ -z "$OPENSCAD_TARGET" ]]; then
  echo "ERROR: OpenSCAD not found." >&2
  echo "  Install locally:  brew install openscad  (macOS)  or  apt install openscad  (Linux)" >&2
  echo "  Build Docker:     docker build -t openscad-cli '${CLAUDE_PLUGIN_ROOT:-.}/scripts/docker/openscad/'" >&2
  exit 1
fi

# Run wrapper — transparently handles local binary vs Docker
openscad_run() {
  local mode="${OPENSCAD_TARGET%%:*}"   # "local" or "docker"
  local target="${OPENSCAD_TARGET#*:}"  # binary path or image name
  if [[ "$mode" = "docker" ]]; then
    docker run --rm -v "$PWD:/work" -w /work "$target" "$@"
  else
    "$target" "$@"
  fi
}

openscad_run --version

The openscad_run function wraps every invocation. Usage is identical to calling openscad directly:

openscad_run --export-format binstl -o out.stl model.scad
openscad_run -o preview.png --preview --imgsize=1280,960 model.scad

Docker image: Build with docker build -t openscad-cli hardware/scripts/docker/openscad/ from the repo root. Override the image name with OPENSCAD_DOCKER_IMAGE=my-registry/openscad:latest.

References

• references/language.md — OpenSCAD syntax: modules/functions, variables and scope, control flow, CSG booleans, primitives, transforms, extrusion and projection, import/include/use.
• references/cli.md — full openscad CLI: output and format flags, -D variables, rendering modes, image/camera options, diagnostics, --enable features, headless notes.
• references/design.md — printability heuristics (min wall, overhangs, bridges, clearance, manifold) and 2D-for-laser rules.
• references/workflows.md — end-to-end recipes (parametric STL, 2D DXF, preview PNG, batch variants, mesh conversion, stderr validation).