Docs

How it works

You write a Python script that calls show_object() on a shape. agentcad runs it, produces a versioned STEP file, computes geometric metrics, renders a four-view preview, opens a review viewer, and from the second version onward compares the result against the previous one. Every response is structured JSON.

Static validation catches syntax errors, a missing show_object(), and unresolvable imports in under 100 ms, without consuming a version number or writing to disk.

The operational briefing is agentcad --help. Run it once at the start of a session. That is the source of truth, not this page.

Install

agentcad supports Python 3.10 to 3.12. The OpenCascade bindings it depends on do not exist for 3.13 yet.

python3.12 -m venv .venv
source .venv/bin/activate
pip install 'agentcad[mcp]'
agentcad skill install
agentcad instructions install
agentcad --help

CLI only, without the MCP server: pip install agentcad. With uv: uv tool install --python 3.12 'agentcad[mcp]'.

Reading the output

Four conventions hold across every command. Getting these wrong is the most common way an agent misreads a successful run as a failure.

1. stdout is JSON, stderr is not

Progress lines go to stderr. Merging the streams before a JSON parser corrupts the parse.

agentcad run script.py --output first > result.json
# stdout: the JSON response
# stderr: human-readable progress lines

# WRONG. Progress lines corrupt the parse:
agentcad run script.py --output first 2>&1 | jq .

2. Core success and artifact success are separate

core covers the CAD lifecycle: metrics, validity, STEP export, version registration. When it reports success, the STEP exists and the version is registered. artifacts covers optional post processing, each group reporting pending, success, unavailable, timeout, failed, or skipped.

A failed preview does not undo a successful build. Keep the STEP and retry only the artifact you actually need.

3. outputs are 3D, renders are 2D

outputs holds 3D model artifacts, keyed step, script, stl, glb, obj. renders holds PNGs, keyed by view name or custom angle. Do not look for one inside the other.

4. status has five values

success

The command’s primary work completed.

failed

A script raised. Includes error, and for known failure shapes a suggestion. A version directory is created.

error

A CLI-level problem: missing file, bad arguments, no manifest. Includes message. Nothing is written to disk.

validation_error

A static check failed before the CAD engine started. No version consumed, nothing on disk, under 100ms.

invalid_geometry

The script ran and metrics computed, but the final shape is not a valid solid. No STEP is exported and current does not advance. Check version_recorded and current_advanced.

Commands that read CAD files can also return empty, malformed, unknown_format, display_format, recognized_deferred, or limited, each with a message or suggestion.

Your first run

Initialize a project, write a two-line script, run it, read the JSON.

1. Initialize

agentcad init --name myproject

2. Write script.py. No imports needed; build123d and show_object are pre-injected.

# script.py
box = Box(10, 20, 5)
show_object(box)

3. Run it

agentcad run script.py --output first

4. Read the JSON, trimmed here

{
  "command": "run",
  "status": "success",
  "core": {"status": "success"},
  "artifacts": {
    "preview": {"status": "success"},
    "viewer": {"status": "success"},
    "renders": {
      "status": "skipped",
      "message": "No explicit renders requested."
    }
  },
  "runtime": "build123d",
  "output_type": "single_part",
  "version": 1,
  "label": "first",
  "outputs": {
    "step": "v1_first/output.step",
    "script": "v1_first/script.py"
  },
  "metrics": {
    "dimensions": {"x": 10.0, "y": 20.0, "z": 5.0},
    "volume": 1000.0,
    "surface_area": 700.0,
    "face_count": 6,
    "edge_count": 12,
    "is_valid": true
  },
  "preview": "v1_first/preview.png",
  "viewer": "v1_first/viewer.html",
  "viewer_glb": "v1_first/output.glb"
}

Geometry wrong? Check metrics.dimensions and metrics.volume first. Most problems are visible there before anything is rendered. Use agentcad measure to read feature sizes back off the finished file, and agentcad inspect for topology deep dives.

What lands on disk

Every successful run creates a numbered directory. Nothing overwrites anything.

v1_first/
  output.step       STEP geometry
  output.glb        GLB behind viewer.html
  script.py         copy of the executed script
  meta.json         full run metadata, including runtime and parts
  preview.png       4-view composite: top, bottom, upper iso, lower iso
  viewer.html       review viewer (opens automatically)
  parts/            one preview per named part
  renders/          requested PNG views

  # from v2 onward, against the previous success:
  diff_side.png     side by side
  diff_overlay.png  centered 2D projection map
  diff_volume.png   shared / reference-only / candidate-only 3D volume
  diff_volume.glb   interactive geometry behind diff_volume.png

For the core-only fast path, combine --no-preview --no-diff --no-view. That leaves the STEP, the script, and meta.json with its metrics, plus anything you asked for explicitly.

Command reference

18 commands. Every one returns JSON with command and status.

agentcad init [--name NAME] [--runtime build123d|cadquery] [--force]

agentcad init --name myproject

agentcad run SCRIPT --output LABEL [OPTIONS]

agentcad run script.py --output first --render iso --export stl

agentcad import FILE [--label LABEL] [--init] [--no-view] [--no-diff]

agentcad import bracket.step --init --label vendor_part

agentcad render FILE --view SPEC [--zoom N] [--size WxH] [--msaa N] [--focus x,y,z] [--no-fit] [--name LABEL]

agentcad render v1_first/output.step --view front,top,iso --size 1600x1200 --msaa 4

agentcad export FILE --format stl,glb,obj

agentcad export v1_first/output.step --format stl,glb

agentcad view FILE [FILE_B] [--overlay] [--measure] [--spec SPEC_FILE]

agentcad view v1_first/output.step v2_second/output.step

agentcad parts list|show|view REF [OPTIONS]

agentcad parts view 2 --isolate-group gear --ghost-rest --note 'check tooth spacing'

agentcad measure FILE [OPTIONS]

agentcad measure v2_second/output.step --diameter 6

agentcad inspect FILE [--ids] [--summary] [--limit N] [--no-limit]

agentcad inspect vendor_part.step --summary

agentcad check-spec FILE SPEC_FILE

agentcad check-spec v2_second/output.step spec.json

agentcad diff REF1 REF2 [--visual] [--overlay]

agentcad diff 1 2 --visual

agentcad context

agentcad recover VERSION_DIR [--make-current]

agentcad recover v4_bracket

agentcad docs [SECTION] [--runtime ENGINE]

agentcad docs examples

agentcad skill install | show [--runtime ENGINE]

agentcad skill install

agentcad instructions install [--target auto|agents|claude|all] | show

agentcad instructions install

agentcad feedback "your message" [--max-entries N] [--local-only]

agentcad feedback "inspect output is hard to read when shells are nested"

agentcad subscribe EMAIL

Writing a spec

A spec file turns “done” into something your agent can test against. Write it before the geometry, then check the finished file:

{"features": [
  {"name": "bolt_holes", "type": "cylinder", "diameter_mm": 6, "count": 4}
]}

agentcad check-spec v2_bracket/output.step spec.json

A failing spec is still a successful command. Read passed, matched_features, and missing_features for the verdict. Run agentcad docs check-spec for the full schema.

Script preamble

On the default build123d runtime, every script run by agentcad run has the entire build123d public API available without imports, plus the agentcad helpers:

Box / Cylinder / Sphere / Cone / Torus / Wedge

primitives

Wire / Edge / Face / Solid / Compound / Part

topology types

extrude / revolve / sweep / loft / offset

operations

fillet / chamfer / mirror / scale

modifiers

Plane / Axis / Vector / Location / Locations

positioning

Mode / Align / Kind / Until / Select

enums

BuildPart / BuildSketch / BuildLine

builder contexts

show_object

surface one shape as a named part

show_assembly

surface an intentional multi-body result

load_step / pick_face / pick_edge

editing helpers for imported geometry

naca_wire / spline_wire / polygon_wire / ellipse_wire

wire helpers, return raw OCP shapes

loft_sections / tapered_sweep / elliptical_sweep

sweep helpers

Helpers return raw OCP shapes, so wrap them for build123d: extrude(Face(Wire(naca_wire(...))), amount=5). Explicit imports stay harmless and help editor completion. Run agentcad docs preamble for the authoritative list and agentcad docs examples for worked scripts.

Metrics

Returned on every successful run, saved in meta.json, and compared by agentcad diff.

bounding_box   {x: [min, max], y: [min, max], z: [min, max]}
dimensions     {x, y, z}     bbox extents
volume         float
surface_area   float
center_of_mass {x, y, z}
face_count     int
edge_count     int
is_valid       bool          OCP shape validity

agentcad is unit-agnostic. Scripts default to millimetres, the OpenCascade convention, so volume is mm³ and area is mm² unless your script chose otherwise.

Volume is the trustworthy signal. Face and edge counts are advisory: boolean operations routinely merge coplanar faces, so a feature that adds material can lower face_count.

CadQuery compatibility

CadQuery remains supported for existing projects and scripts. Make the choice explicit so the project, the docs, and the runner stay on one API.

Start a CadQuery project

agentcad init --name legacy-model --runtime cadquery
agentcad docs quickstart --runtime cadquery

Run one legacy script inside a build123d project

agentcad docs preamble --runtime cadquery
agentcad run legacy.py --output legacy --runtime cadquery

Keep each script on one CAD API. A clear mismatch fails before consuming a version and reports the exact override to use. See agentcad docs runtimes.

MCP integration

For native tool integration with Claude Code, Cursor, Windsurf, or any MCP-compatible agent:

pip install 'agentcad[mcp]'

Add to .mcp.json:

{"agentcad": {"command": "python", "args": ["-m", "agentcad.mcp"]}}

When agentcad lives in a project virtual environment, point at that interpreter instead so the server does not launch under the wrong Python:

{"agentcad": {
  "command": ".venv/bin/python",
  "args": ["-m", "agentcad.mcp"]
}}

Exposed as tools: run, render, export, measure, inspect, check_spec, diff, view, docs, context, recover. Same JSON as the CLI, same fields. Every tool takes a cwd pointing at the project directory. The CAD runtime stays warm between calls, so later runs skip the cold import.

Built-in docs

agentcad ships its full documentation inside the CLI as JSON, so an agent never needs this website. Run agentcad docs for everything, or name a section:

agentcad docs quickstart     # first-script walkthrough
agentcad docs examples       # worked scripts
agentcad docs patterns       # idioms and footguns
agentcad docs editing        # editing imported geometry
agentcad docs measure        # dimensional verification
agentcad docs parts          # named parts and groups
agentcad docs schema         # full response contract
agentcad docs recovery       # picking up after an interruption

All 26 sections: build123d, cadquery, check-spec, commands, daemon, editing, examples, export, feedback, helpers, inspect, install, mcp, measure, metrics, parametric, parts, patterns, preamble, quickstart, recovery, render, runtimes, schema, validation, workflow.

If your agent gets stuck

Run agentcad feedback from inside the project:

agentcad feedback "the inspect output is hard to read when shells are nested"

Casual, partial, or “just a thought” messages from agents mid-task are exactly the signal we want. They surface friction we would otherwise never see. The session log ships with the message as context.