# How to Use text-to-cad to Generate CAD Models: A Complete Workflow Guide

> Learn how to use text-to-cad to generate CAD models. Follow our guide to install, write Python scripts with the @step decorator, and emit STEP files.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Install the skill with `npx skills add earthtojake/text-to-cad`, write a Python model script using the `@step` decorator from the `cadgen` library, then execute it with `python` to emit validated STEP files.**

The **text-to-cad** repository provides an open-source skill for generating parametric CAD models through code. It wraps the `cadgen` distribution to convert Python scripts into industry-standard STEP files, complete with inspection tools and a built-in viewer for interactive validation.

## Installing the text-to-cad Skill and Runtime

### Install the Skill via Skills CLI

The preferred method pulls the entire repository and registers the CAD skill with a single command. This places the skill definition under `skills/cad/` and resolves the pinned `cadgen` dependency specified in [`skills/cad/requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/requirements.txt).

```bash
npx skills add earthtojake/text-to-cad

```

### Configure the Python Environment

After installation, resolve the runtime dependencies and install a headless browser for snapshot generation. The requirements are documented in [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md).

```bash
python -m pip install -r requirements.txt
python -m playwright install chromium

```

The `playwright` installation is mandatory for the `snapshot` command used to generate PNG previews of your models.

## Writing CAD Models with the text-to-cad Skill

### The Decorator-Based Build Pattern

Models are Python files that define a *parameter-less* function decorated with output format decorators. The primary decorator `@step` emits a STEP file, while alternatives like `@stl`, `@glb`, and `@threemf` produce mesh-only outputs. These decorators are implemented in [`packages/cadgen/src/cadgen/step.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/step.py).

The function must return a geometry object built with the `build123d` API. The decorator handles the export logic, writing the file adjacent to your script.

### Model Script Structure

A minimal model imports `build123d` through the `cadgen` namespace and declares its output format. When executed, the script writes `bracket.step` to the project folder.

```python

# bracket.py

from cadgen import build123d as bd
from cadgen import step

WIDTH = 10.0

@step  # → writes bracket.step alongside this file

def bracket():
    return bd.Box(WIDTH, 10, 10)

if __name__ == "__main__":
    bracket()

```

Constants defined at module scope become adjustable parameters. Changing `WIDTH` and rerunning the script regenerates the geometry without modifying the underlying logic.

## Building and Validating CAD Models

### Executing the Build

Run the model script with the standard Python interpreter. The console emits a status line confirming the build, while the underlying system invokes `python -m cadgen.cli step build` transparently.

```bash
python bracket.py

```

This creates `bracket.step` in your working directory. If the model is unchanged, the system uses a cached version stored in `~/.cache/cadgen` to skip redundant computation.

### Geometry Inspection

Once the STEP file exists, validate its topology and extract measurements using the `cadgen step inspect` sub-commands defined in the [`step.py`](https://github.com/earthtojake/text-to-cad/blob/main/step.py) implementation.

```bash
cadgen step inspect refs bracket.step --facts --planes --positioning

```

The output lists selector references (e.g., `#o1.2`), bounding boxes, and datum planes, allowing you to verify critical dimensions programmatically.

### Generating Visual Previews

Create a PNG snapshot for documentation or review pipelines. This requires the Chromium browser installed during setup.

```bash
cadgen step snapshot bracket.step tmp/bracket.png

```

The snapshot command renders the STEP file through the CAD Viewer engine without launching the interactive browser window.

## Previewing and Iterating on Models

### Launching the CAD Viewer

If the `$cad-viewer` skill is installed, you can open an interactive session. The viewer serves the STEP file locally and returns a URL such as `http://localhost:8000/viewer?file=bracket.step`, allowing stakeholders to rotate, section, and measure the model in a browser.

The viewer entry point is located at [`packages/cadgen/src/cadgen/viewer/main.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py).

### Managing Build Cache

The `cadgen` store tracks file freshness to avoid unnecessary rebuilds. Force a fresh build with the `--force` flag, or purge specific entries from the cache.

```bash
python bracket.py --force
cadgen store forget bracket.py

```

This cache management ensures rapid iteration when adjusting parameters across multiple design variations.

## Summary

- **Install** the skill via `npx skills add earthtojake/text-to-cad` and resolve Python dependencies from [`skills/cad/requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/requirements.txt).
- **Author** models using the `@step` decorator and the `build123d` API, returning geometry from a parameter-less function.
- **Build** by running the Python script directly, which emits STEP files alongside the source code.
- **Validate** geometry using `cadgen step inspect` with flags like `--facts` and `--planes`.
- **Preview** interactively through the CAD Viewer or generate static PNG snapshots with `cadgen step snapshot`.
- **Iterate** efficiently using the `~/.cache/cadgen` store, forcing rebuilds with `--force` when necessary.

## Frequently Asked Questions

### What file formats does text-to-cad support?

The skill primarily generates **STEP** files via the `@step` decorator. For mesh workflows, you can use `@stl`, `@glb`, or `@threemf` decorators to export directly to those formats without creating a STEP intermediate, as documented in [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md).

### How do I force a rebuild when the cache is stale?

Use the `--force` flag when running your model script (e.g., `python bracket.py --force`). Alternatively, run `cadgen store forget bracket.py` to remove the specific entry from `~/.cache/cadgen` before building.

### Can I view the generated models without installing extra software?

Yes, provided the `$cad-viewer` skill is installed. The viewer runs locally and serves the STEP or mesh file at a `localhost` URL, requiring only a web browser to interact with the 3D geometry.

### Where does text-to-cad save the generated files?

By default, output files are written to the same directory as the source Python script. The `@step` decorator automatically names the output file to match the function name (e.g., `bracket.step` for a function named `bracket`).