# Text-to-CAD Quick Start Guide: Generate CAD Models from Natural Language

> Learn Text-to-CAD with our quick start guide. Generate manufacturing-ready STEP files from natural language using Python scripts and get instant visual feedback.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: getting-started
- Published: 2026-08-04

---

**The text-to-CAD repository transforms natural language prompts into manufacturing-ready STEP files using Build123d Python scripts, complete with validation tools and a web-based viewer for immediate visual feedback.**

This guide walks through the **earthtojake/text-to-cad** repository, a modular library of agent skills that automate CAD generation and robot description workflows. The project follows a strict separation of concerns across skills, shared packages, and a lightweight viewer, making it straightforward to generate, inspect, and hand-off geometric artifacts. Whether you are creating individual parts or complex assemblies, this text-to-CAD quick start guide covers the essential architecture, CLI commands, and validation steps required to move from prompt to physical design.

## Repository Architecture and Layer Design

The codebase organizes functionality into distinct layers to keep the system modular and extensible. Understanding these boundaries is critical for contributing new skills or debugging generation pipelines.

- **Skills Layer**: Individual capabilities reside under `skills/<skill>/`, each containing a markdown [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) that documents its API and data flow. For example, [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) defines the CAD generation contract, while [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md) handles visualization hand-offs.
- **Packages Layer**: Reusable runtime code lives in `packages/`. The `packages/cadpy` directory specifically houses Python helpers for STEP, STL, GLB, and URDF generation that multiple skills import.
- **Viewer Layer**: A lightweight web viewer located in `viewer/` previews STEP, STL, GLB, G-code, and robot description files. Configuration is managed in `viewer/vite.config.mjs`.
- **Benchmarks and Assets**: Example models and visualizations sit in `benchmarks/` and `assets/`. These are large binary files tracked with Git LFS to maintain lightweight repository clones.
- **CI and Testing**: The [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) harness runs automated validation on the `develop` branch. Note that pull requests must target `develop`, while `main` remains a publish-only branch as defined in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md).
- **Documentation Site**: A Next.js application in `docs/` publishes the skill reference to `https://www.cadskills.xyz`, pulling markdown directly from the `skills/` directory.

## Installation and Environment Setup

Install the skill library using the preferred package manager method. This configures the CLI tools and symlinks required to run skills from any directory.

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

```

After installation, ensure Git LFS is initialized if you plan to access benchmark models or asset files stored in the repository. Remember that active development happens on the `develop` branch; direct commits to `main` are restricted according to the branching policy in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md).

## The Six-Step CAD Generation Workflow

The core workflow moves from natural language to a validated, viewable artifact. Each step corresponds to a specific script or skill in the repository.

### 1. Author the Build123d Source

Create a Python file that implements the `gen_step()` function. This function must return a Build123d object or assembly. Place reusable geometry logic in `packages/cadpy` to keep your source file clean.

```python

# my_part.py

from build123d import *

def gen_step():
    return Box(10, 10, 5)

```

### 2. Generate the Primary STEP File

Run the STEP generation script, specifying whether the output is a `part` or `assembly`. This creates the primary artifact; all secondary exports (STL, 3MF, GLB) are derived from this file as documented in [`references/supported-exports.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/supported-exports.md).

```bash
python scripts/step my_part.py --kind part --out my_part.step

```

### 3. Inspect Geometry Selectors

Validate that the generated geometry matches your intent by inspecting faces, edges, and positioning data. This is crucial for assemblies where parts must interface correctly.

```bash
python scripts/inspect refs my_part.step --facts --planes --positioning

```

### 4. Create Visual Snapshots

Generate PNG snapshots for documentation or reviewer feedback. The snapshot command renders the STEP file from a standard camera angle.

```bash
python scripts/snapshot my_part.step --out snapshots/my_part.png

```

### 5. Launch the CAD Viewer

Start the local viewer server, binding to `127.0.0.1` and pointing the `--dir` flag to your absolute `models/` path.

```bash
npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models

```

### 6. Hand Off to the Viewer

The viewer returns a JSON line containing a URL. Navigate to this address to preview your model. The URL follows the pattern:

```

http://127.0.0.1:4178/?dir=/absolute/path/to/text-to-cad/models&file=my_part.step

```

Alternatively, use the `$cad-viewer` skill to automate this hand-off from your agent workflow.

## Locating Standard Components with `$step-parts`

Avoid modeling common hardware from scratch by using the `$step-parts` skill. This searches an internal library of off-the-shelf STEP components and returns an absolute file path ready for import.

```bash
step-parts find "M4 socket head cap screw"

```

Import the returned path directly into your assembly script to maintain accurate geometry for bolts, nuts, and standard structural elements.

## Key Reference Files and Documentation

Navigate the codebase efficiently by bookmarking these critical files:

- **[`README.md`](https://github.com/earthtojake/text-to-cad/blob/main/README.md)**: Project overview, quick-start snippets, and screenshots.
- **[`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md)**: Repository policies, symlink layout, and the `develop`-versus-`main` branching strategy.
- **[`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md)**: Complete CAD skill definition, including all CLI flags for `scripts/step`.
- **[`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md)**: Viewer startup options and URL parameter specifications.
- **`scripts/step`**: Entry point for STEP generation. While this appears in the root scripts directory, the core logic is implemented in `packages/cadpy`.
- **`packages/cadpy`**: Reusable Python modules for geometric operations and file format conversions.
- **[`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh)**: Entry point for the continuous integration test suite.
- **`docs/`**: Source for the public documentation site at `cadskills.xyz`.

## Summary

- **Install** the environment with `npx skills install earthtojake/text-to-cad` and develop on the `develop` branch.
- **Generate** geometry by implementing `gen_step()` in Build123d and running `python scripts/step` to produce validated STEP files.
- **Validate** designs using `scripts/inspect` for geometric accuracy and `scripts/snapshot` for visual confirmation.
- **Visualize** models by serving the viewer from `viewer/` and accessing the generated URL with absolute path parameters.
- **Reference** [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) files in `skills/` subdirectories for detailed API documentation and extension points.

## Frequently Asked Questions

### What is the primary output format of the text-to-CAD workflow?

The system treats **STEP files** as the single source of truth for all geometry. Secondary formats like STL, 3MF, and GLB are derived exports generated from this primary STEP artifact, ensuring dimensional consistency across manufacturing workflows.

### How do I start the CAD viewer to preview my models locally?

Start the viewer by running `npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models` from the repository root. The process outputs a URL containing absolute path parameters; navigate to this link to inspect STEP, STL, or GLB files rendered in the browser.

### Where is the core STEP generation logic implemented?

While you invoke generation via `scripts/step` in the root directory, the actual implementation resides in `packages/cadpy`. This package contains reusable Python helpers for constructing STEP data, handling STL tessellation, and generating URDF robot descriptions.

### Can I use standard hardware like bolts and screws in my assemblies?

Yes. The `$step-parts` skill provides a CLI to locate off-the-shelf components. Running `step-parts find "M4 socket head cap screw"` returns a STEP file path that can be imported into your Build123d assembly, eliminating the need to model common fasteners manually.