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

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.

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.

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.

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.

# 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.

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 implementation.

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.

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.

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.

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.
• 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.

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).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}