/cad

name: cad
description: Creates and edits parametric CAD parts, assemblies and 2D profiles as Python build123d models that text-to-cad's server builds and the CAD Viewer shows live; exports STEP, STL, 3MF, GLB, DXF and xbf files on request; resolves prompt references, measures geometry, checks whether a part can be machined, cut and bent, molded or printed, and articulates or animates assemblies. Use for 3D CAD modeling, editing a model script (any change to a part's or assembly's `.py`), organizing a CAD project, exporting or converting CAD files, DXF files, flat patterns, gaskets and laser or waterjet cut layouts, Quick Edit prompts, mechanisms, and explode or showcase animations. Opens and reviews existing XBF, STEP/STP, STL, 3MF, GLB and DXF files in the CAD Viewer. Not for the robot and world descriptions the robot-simulation skill writes.
license: MIT
metadata:
  repository: earthtojake/text-to-cad

CAD modeling and inspection

A model is a Python function; running its script rebuilds it in text-to-cad's warm server, and the page the person has open updates. Files are exports, made when asked.

Start with the task

| Task | Start with | Reference | | --- | --- | --- | | **Create or edit a part or assembly** | The project's model script, or a new one ([below](#write-a-model-and-run-it)); a part the request says how to make is designed for that process from the first line ([Design for the process](#design-for-the-process)). | [Models](references/model-contract.md), [build123d](references/build123d-modeling.md), [positioning](references/positioning.md) | | **Organize a CAD project** | The project's existing layout. | [Project layout](references/project-layout.md) | | **Export STEP, STL, 3MF, GLB or xbf** | `cad model export <id> <file>`. | [Exports](references/exports.md) | | **Make a 2D profile, flat pattern or DXF** | A model that returns 2D geometry on z=0, then `cad model export <id> part.dxf`. | [2D profiles and DXF](references/2d-profiles-and-dxf.md) | | **Use a vendor STEP, an xbf or a scan in a model** | `step.read`, `xbf.read` or `stl.read` in the body. | [Inputs](references/model-contract.md#inputs) | | **Resolve a reference from a prompt** | `cad model inspect <id> '<ref>'`. | [References](references/inspection-and-validation.md#references) | | **Measure or check geometry** | A check script that calls the model. | [Inspection](references/inspection-and-validation.md) | | **See a model, a view or a pose** | `cad model snapshot <id> out.png`. | [Snapshots](references/snapshot-review.md) | | **Articulate a mechanism** | build123d joints in the body, then `cad.build123d`. | [Kinematics](references/kinematics.md) | | **Find how far each joint can move** | `cad model ranges <id>`, then the ranges in the body. | [Joint stops](#joint-stops) | | **Explode, reveal or showcase a model** | `cad.build123d`'s `animation()` in the body. | [Animation](references/animation.md) | | **Open an existing XBF, STEP/STP, STL, 3MF, GLB or DXF** | Show it to the user. | [Show the model](#show-the-model) | | **Can it be machined, cut and bent, molded or printed?** | The part's model or file, its material and the process the request names or implies; with none, no check. | [Can it be made?](#can-it-be-made) | | **Will it hold under a load, how far does it bend?** | The fea skill ($fea), on the model's id or its STEP or xbf. | Its study reference |

Setup and paths

Run the `cad` command (`~/.local/bin/cad` where it is not on your PATH; `cad.exe` on Windows). If it is missing, install text-to-cad, outside a sandbox or with its permission:

curl -fsSL https://texttocad.dev/install.sh | sh

On Windows, in PowerShell: `irm https://www.texttocad.dev/install.ps1 | iex`. If the CAD app was only just added, its server may still be starting: try again for up to a minute first. `cad doctor --check` explains any other failure, changing nothing; `cad doctor` repairs what it reports. Tell the person any next step `cad setup` prints.

One server runs for the installation: the first run starts it, every run and every command goes through it, and it serves the viewer. `cad status` lists its workers and the documents it holds; `cad stop` stops it. A build cut off by the shell's time limit keeps running in the server; run the same command again and it waits for that build and replays it (`cad status` shows it). Give a cold build of a large model the shell tool's longest timeout, or run it in the background.

Build every model with `cad run`, exactly like `uv run`: the same options and the same script header, with nothing to set up. cad is pinned to this computer's release and its integrations come from the script's imports (`import build123d` is the build123d integration), so a header names only the script's own packages, never a version of cad:

# /// script
# dependencies = ["pandas>=2"]
# ///

A one-off dependency is `--with`; a script inside a Python project runs with the project's dependencies and lock. A run that stops on an import or a requirement says what to change in one line. [Environments](references/environments.md) has the details: `--with`, projects and their locks, private indexes and the network.

Command-line paths, and the paths `step.read`, `xbf.read`, `stl.read` and a type's `export` take, are relative to the working directory, as are a model's own file reads. Anchor them on `__file__` in code that must run from any folder.

Write a model and run it

A part or an assembly is a function with no parameters, decorated `@model` (or with its file decorators, never both), that returns a build123d shape. Its dimensions are the arguments of a plain helper function, and each configuration is a `@model` of its own, with its own id and page; constants several models share live in a module they import. A call builds it and returns its document: a handle with `.id`, `.url`, `.shape` (the built shape) and `.export(...)`. For example, `src/bracket.py`:

import