Readable layout
---
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 `. | [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 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 ''`. | [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 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 `, 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:
```bash
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:
```python
# /// 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`:
```python
import build123d as bd
from cad import model
def bracket_body(width, thickness, bore):
body = bd.Box(width, 20, thickness)
hole = bd.Cylinder(bore / 2, thickness)
body = body - hole
body.label = "bracket"
body.color = "#4a6fa5"
return body
@model
def bracket():
return bracket_body(40, 6, 8)
@model
def bracket_wide():
return bracket_body(60, 6, 8)
if __name__ == "__main__":
bracket()
bracket_wide()
```
```bash
cad run src/bracket.py
```
```text
built src/bracket.py::bracket cold in 2.61s: bodies 1 run; 6 misses, 0 hits; body 0.01s, names 0.00s, document 0.00s
parts 1 · bounds 40 × 20 × 6 mm · joints 0 · sequences 0
id: 0dc50a92-a21f-5895-a245-ebdeb5352f3b
view: http://127.0.0.1:54360/0dc50a92-a21f-5895-a245-ebdeb5352f3b?token=...
built src/bracket.py::bracket_wide warm in 0.01s: bodies 1 run; 6 misses, 0 hits; body 0.01s, names 0.00s, document 0.00s
parts 1 · bounds 60 × 20 × 6 mm · joints 0 · sequences 0
id: 966d03a5-7b43-5bed-b75c-eb67d56c72d2
view: http://127.0.0.1:54360/966d03a5-7b43-5bed-b75c-eb67d56c72d2?token=...
```
Each call the script's `__main__` makes prints how its model built, the delta under it
(parts, bounds, joints and sequences), its document's `id:` and its page, `view:` (the
handle's `.id` and `.url`). An unchanged rerun prints `took ... nothing ran` instead. Give the
user the page once ([Show the model](#show-the-model)) and use the id for every command
after it. The id comes from the
script's path and the function's name, or the script's folder and an explicit `@model(name="...")`,
so it is the same run after run, and the open page follows every run. A model's name is its identity
within its namespace, the function's name by default, `name=` gives it another. The namespace
is the script's folder; two explicit names in it must differ.
- **Running the script is the rebuild.** It writes no file. The server's warm worker for
the script replays every operation an edit did not reach, so a comment re-runs nothing
and a dimension edit re-runs what reads it
([what a run runs](references/model-contract.md#what-a-run-runs)). Decoration only
declares: keep the calls under `if __name__ == "__main__":` so other scripts can import
the models.
- **`@memo` marks stages, never parts.** The server already replays every kernel call, so
mark only a function holding seconds of kernel work that an edit elsewhere leaves
alone, such as a whole sub-assembly stage; never a part, never a helper called many
times ([`@memo`](references/model-contract.md#memo-marks-stages)).
- **An assembly calls its parts.** Its body calls each part model and composes its shape
(`plate().shape`), places and labels it, and returns a `Compound`. Each child builds in
the same run and keeps its own document and id. Running a child's script alone leaves the assemblies that
use it as they were: run the assembly.
- **`import build123d as bd`, and use it attribute-style** (`bd.Box`). The import is lazy:
the kernel loads on first use, in the worker. `from build123d import Box`, or a
module-level `bd.Color(...)` or `bd.Align` default, loads it at that line instead.
- **Colours are sRGB**, as a person picks them: `part.color = "#4a6fa5"` (`"#4a6fa5cc"` with
alpha). `part.color` is build123d's: it takes no 0-255 integers (OCCT's `Color out`), which
`paint` does. Import `metals` from `bd_materials`; assign a native material with
`part.material = metals.aluminum()` (the families and their materials are listed in
[colour and materials](references/build123d-modeling.md#colour-and-materials); plain steel is
`metals.mild_steel()`); boards, electronic parts and finishes (solder mask, ENIG, anodized,
powder coat) are `cad.build123d.materials`' named looks.
- **Inputs** are `step.read`, `xbf.read` and `stl.read` in the body, and any file its
Python opens, each tracked by its bytes. The clock, environment variables and
randomness are not seen: a body is a function of its code and its inputs. Compose
project models by calling them, never by reading a file the project exported.
- **References** to faces, edges and parts come from `cad model inspect [ref]`, and the
body picks the same element with build123d's selectors; verify with a snapshot when in
doubt ([references](references/inspection-and-validation.md#references)).
- **A shape with no function** (a notebook cell, a REPL) is handed over:
`model(shape, name="plate")` returns the same handle, and no command builds it again.
- **The server never reruns code.** A restart reopens every document from the server's
cache, as last built. When the cache holds no file of one (deleted by hand, or never
saved), the page, `cad model inspect ` and `cad_show` print the command that brings it
back (`cad run src/bracket.py`). Run it.
- Model units are millimetres, +Z up.
- An image without a scale sets no fit dimension, and a drawing's units, projection and
revision decide how its numbers read. A missing or conflicting dimension that changes
the result is the person's to settle; a value chosen in its place is an assumption.
## Files, when asked
A file is an action on the document the server holds, never part of the model: no code
change and no rebuild, written at once. It holds what the document held when it was
written, so a change made after it is in the file only once it is written again. Write one
when the person asks for it:
```bash
cad model export "$ID" STEP/bracket.step STL/bracket.stl GLB/bracket.glb 3MF/bracket.3mf
```
A project with standing deliverables gets an `exports.py` that imports its models and
calls `model.export(x, path, ...)` on each (`from cad import model`; `x` a model call's handle); running it rewrites every deliverable
([exports](references/exports.md)). An export takes a document and its destinations,
and nothing else: a posed file is a model that returns the posed assembly
(`posed(arm(), "folded")`), and a part on its own is the part's own model. A DXF is the export of a
model that returns 2D geometry, a profile or a flat pattern, and a solid is refused
([2D profiles and DXF](references/2d-profiles-and-dxf.md)). An STL or 3MF for printing a part with fits