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 (volume, dimensions, validity, face/edge counts), and optionally renders PNG views or exports STL / GLB / OBJ. Every response is structured JSON.

Pre-execution validation catches syntax errors, missing show_object(), and unresolvable imports in under 100 ms — without consuming a version number or writing to disk. Once geometry runs, the version directory (e.g. v3_strut_fittings/) holds the STEP, the script, full metadata, the preview PNG, and any renders.

The full operational briefing is in agentcad --help. Run it once at the start of a session — that’s the source of truth, not this page.

What you can do

init

— start a new project

run

— execute a script, produce versioned STEP + metrics

render

— PNG views from any angle for visual verification

export

— STL, GLB, OBJ for 3D printing and web viewers

inspect

— topology report for debugging geometry issues

diff

— compare two versions to track design iteration

view

— open a STEP or GLB in the browser (three.js viewer)

docs

— 17 sections of built-in JSON documentation

feedback

— submit a friction note from inside a session

Install

Requires Python 3.10–3.12. CadQuery / OpenCascade does not support 3.13+.

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

CLI-only (no MCP server): pip install agentcad

Your first edit

Initialize a project, write a one-line CadQuery script, run it, and read the JSON.

1. Initialize

agentcad init --name myproject

2. Write script.py (no imports needed — cq and show_object are pre-injected)

# script.py
box = cq.Workplane('XY').box(10, 20, 5)
show_object(box)

3. Run it

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

4. Read the JSON

{
  "command": "run",
  "status": "success",
  "runtime": "cadquery",
  "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"
}

Geometry wrong? Check metrics.volume and metrics.dimensions first — most issues are visible there before you render. Use agentcad inspect for topology deep-dives (hollow shells, inverted normals, validity).

Command reference

Every command returns JSON with command and status keys. status is one of success, failed, error, or validation_error.

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

agentcad init --name myproject --runtime cadquery

agentcad run SCRIPT --output LABEL [flags]

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

agentcad render STEP --view SPEC [--zoom N] [--focus x,y,z] [--no-fit] [--name LABEL]

agentcad render v1_first/output.step --view front,top,iso --zoom 1.5

agentcad export STEP --format stl,glb,obj

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

agentcad inspect STEP

agentcad inspect v1_first/output.step

agentcad diff REF1 REF2

agentcad diff 1 2

agentcad context

agentcad view FILE

agentcad view v1_first/output.step

agentcad docs [SECTION] [--runtime ENGINE]

agentcad docs preamble

agentcad feedback "your message"

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

agentcad skill install

agentcad subscribe EMAIL

Script preamble (what’s pre-injected)

Every script run by agentcad run has these names available without imports:

cq

— the cadquery module (= import cadquery as cq)

show_object

— CQGI's show_object — every named call surfaces a discrete solid

translate

— translate(shape, x, y, z) → new shape

rotate

— rotate(shape, axis, angle_deg) — axis ∈ 'X','Y','Z', right-hand rule

mirror_fuse

— mirror_fuse(shape, plane='XZ') — mirror about XZ/YZ/XY and fuse

loft_sections

— loft_sections(sections, smooth=True) — loft a list of TopoDS_Wire

tapered_sweep

— tapered_sweep(spine, radii) — circular sections along a spine

elliptical_sweep

— elliptical_sweep(spine, x_radii, y_radii) — independent X/Y radii

naca_wire

— naca_wire(y, le_x, te_x, thickness, profile='0012') — NACA airfoil

bbox_point

— bbox_point(shape, x, y, z) — query bbox corners ('min'|'center'|'max')

place_at

— place_at(shape, from_pt, to_pt) — translate so from_pt → to_pt

assemble

— assemble(*shapes) — combine into a Compound ready for show_object

ellipse_wire / spline_wire / polygon_wire / rounded_rect_wire

— wire builders for sections and profiles

involute_gear_profile

— involute_gear_profile(module, teeth, pressure_angle=20) — gear wire

Explicit imports still work — adding import cadquery as cq is harmless. For non-standard modules (e.g. OCP.gp) you still need the import. Run agentcad docs preamble for the full list.

Response schema

All commands return JSON with command and status. Successful run responses include runtime, version, outputs, and metrics.

success

— completed normally

failed

— script error. Version IS consumed; creates v{N}_{label}_failed/

error

— CLI error (bad args, missing file, ambiguous runtime). No version consumed

validation_error

— static check failed (syntax, missing show_object, bad import). No version consumed; instant (<100 ms)

Metrics returned on every successful run:

bounding_box   {x: [min, max], y: [min, max], z: [min, max]}
dimensions     {x, y, z}             bbox extents
volume         float                  unit-agnostic (mm defaults → mm³)
surface_area   float
center_of_mass {x, y, z}
face_count     int                    unique faces
edge_count     int                    unique edges
is_valid       bool                   BRepCheck shape validity

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"]}}

All agentcad commands are exposed as native agent tools — no shell parsing, structured parameters in, structured JSON out, and the CadQuery process stays warm so subsequent runs skip the 3–5 s cold import.

Built-in docs

agentcad ships its full documentation inside the CLI as JSON. Run agentcad docs to list every section, or pass a section name to read one:

agentcad docs                # all sections + content
agentcad docs preamble       # what's pre-injected
agentcad docs quickstart     # first-script walkthrough
agentcad docs patterns       # idioms + footguns
agentcad docs helpers        # geometry helper API
agentcad docs metrics        # full metrics schema
agentcad docs mcp            # MCP setup
agentcad docs daemon         # persistent worker mode

Sections: commands, daemon, export, helpers, inspect, install, mcp, metrics, parametric, parts, patterns, preamble, quickstart, render, 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’d otherwise never see. The current session log ships with the message as context.