# Text-to-CAD API Reference: CLI and Skill-Based CAD Generation

> Explore the Text-to-CAD API reference. Generate STEP files, inspect geometry, and create snapshots with this skill-based CLI. Learn how to use skill manifests for deterministic Python scripting.

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

---

**TLDR:** The Text-to-CAD API is a skill-based command-line interface that enables agents to generate STEP files, inspect geometry, and create visual snapshots through deterministic Python scripts, using skill manifests in `skills/*/SKILL.md` to define usage contracts rather than traditional HTTP endpoints.

The `earthtojake/text-to-cad` repository provides a deterministic, file-based API for automated CAD generation and inspection. Unlike conventional REST services, this **Text-to-CAD API reference** documents executable skill definitions and Python packages that transform natural language prompts into geometric artifacts through command-line invocations.

## Architectural Overview

The API consists of four distinct layers that process natural language requests into verified CAD artifacts.

**Skill definitions** located in `skills/*/SKILL.md` files (such as [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) and [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md)) serve as markdown manifests describing usage contracts, required inputs, and output conventions for each capability. These files declare the **non-negotiables** that all operations must follow, including STEP as the canonical artifact format.

**Runtime CLI tools** in the `scripts/` directory provide thin wrappers around the underlying Python libraries. The `scripts/step` command generates STEP files from build123d Python generators, while `scripts/inspect` handles geometric inspection and `scripts/snapshot` creates visual verification assets.

**Python core packages** under `packages/cadpy_*` implement the actual STEP and GLB creation logic. The `AssemblyHelper` class and metadata utilities in `packages/cadpy_metadata` handle assembly operations and file format conversions.

**Viewer integration** operates through the `$cad-viewer` skill, which launches a local web server and returns URLs like `http://localhost:4178/?dir=<repo>/models&file=<artifact>.step` for interactive model preview.

## Generating STEP Files with scripts/step

The `scripts/step` command serves as the primary entry point for CAD generation. It accepts Python generator files using the build123d library and produces canonical STEP artifacts.

Generate a part from a build123d script:

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

```

This creates `my_part.step` alongside the generator and registers the file with the viewer runtime. The `--kind` parameter specifies the generator type, typically `part` for single components or `assembly` for multi-body designs.

Export secondary formats alongside the primary STEP file:

```bash
python scripts/step --export stl my_part.step
python scripts/step --export glb my_part.step

```

These commands produce side-car files in STL, 3MF, or GLB formats placed adjacent to the primary STEP artifact.

## Inspecting Geometry with scripts/inspect

The `scripts/inspect` utility provides geometric analysis and selector-based fact extraction for generated STEP files.

Inspect geometric references and positioning data:

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

```

This outputs structured data including selector-based facts (formatted as `#o1.2`), plane definitions, and spatial positioning information that agents use for alignment and verification.

## Creating Visual Snapshots with scripts/snapshot

Visual verification is mandatory for any geometry change according to the skill contracts. The `scripts/snapshot` command generates deterministic animations and static images.

Create a GIF animation for verification:

```bash
python scripts/snapshot my_part.step --output snapshots/my_part.gif

```

This produces a visual record that must be attached to final responses, ensuring deterministic verification of the generated geometry.

## Viewer Integration and Hand-off

The CAD viewer skill launches a local web interface for interactive model inspection. Invoke the viewer through the `cad-viewer` command:

```bash
cad-viewer --open my_part.step

```

This launches the server (if not already running) at `http://127.0.0.1:4178` and returns a complete URL:

```

http://127.0.0.1:4178/?dir=/home/user/repo/models&file=my_part.step

```

The URL format includes the directory path and filename parameters, enabling direct browser access to the model.

## Programmatic API Usage

Integrate the Text-to-CAD API into Python applications using standard subprocess calls.

```python
import subprocess
import json

def generate_step(generator_path):
    """Generate STEP file from build123d generator."""
    subprocess.run(
        ["python", "scripts/step", "--kind", "part", generator_path],
        check=True
    )

def inspect_geometry(step_file):
    """Extract geometric facts from STEP file."""
    result = subprocess.run(
        ["python", "scripts/inspect", "refs", step_file, "--facts"],
        capture_output=True,
        text=True,
        check=True
    )
    return json.loads(result.stdout)

# Usage

generate_step("my_part.py")
facts = inspect_geometry("my_part.step")

```

This pattern allows agents to invoke the full API surface while processing the structured JSON outputs from inspection commands.

## Key Files and Implementation

- **[`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md)** – Defines the core CAD skill contract including non-negotiable requirements that STEP is the canonical artifact and snapshots are mandatory.
- **[`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md)** – Specifies URDF robot description generation and validation protocols.
- **[`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md)** – Documents the viewer hand-off protocol and URL construction format.
- **`scripts/step`** – CLI entry point for STEP generation and secondary format export.
- **`scripts/inspect`** – Geometry inspection utility for refs, measurements, and alignment data.
- **`scripts/snapshot`** – Visual snapshot creation for PNG/GIF verification assets.
- **`packages/cadpy_metadata`** – Core Python library containing `AssemblyHelper` and metadata handling for STEP/GLB operations.
- **[`references/cad-brief.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/cad-brief.md)** – Authoring guide for prompt briefs and positioning constraints consulted by the CLI.

## Summary

- The Text-to-CAD API uses **skill-based CLI tools** rather than HTTP endpoints, with commands located in `scripts/step`, `scripts/inspect`, and `scripts/snapshot`.
- **STEP files** serve as the canonical artifact format, with secondary exports (STL, GLB) generated as side-cars.
- **Skill contracts** defined in `skills/*/SKILL.md` enforce non-negotiable requirements including mandatory visual snapshots for all geometry changes.
- **Python integration** occurs through subprocess invocation of CLI tools, with `packages/cadpy_metadata` providing the underlying geometric processing via `AssemblyHelper`.
- **Viewer hand-off** generates localhost URLs with directory and file parameters for interactive model verification.

## Frequently Asked Questions

### What is the entry point for the Text-to-CAD API?

The primary entry point is the `scripts/step` command, which accepts build123d Python generators and produces STEP files. Unlike traditional APIs, there is no HTTP endpoint; instead, agents invoke the Python script directly from the shell or through subprocess calls.

### How does the API handle different file formats?

The API treats STEP as the canonical format as specified in [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md). Secondary formats like STL, 3MF, and GLB are generated through the `--export` flag in `scripts/step` or via the `packages/cadpy_metadata` conversion utilities, but always as side-cars to the primary STEP artifact.

### Can I use the Text-to-CAD API without launching the viewer?

Yes. The viewer integration through `cad-viewer` and [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md) is optional for headless workflows. The core generation and inspection tools (`scripts/step`, `scripts/inspect`) operate independently and only require the Python packages in `packages/cadpy_*`.

### Where are the usage contracts and constraints defined?

Skill contracts are defined in markdown manifests within the `skills/` directory. The [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) file contains the primary contract including non-negotiables, while [`references/cad-brief.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/cad-brief.md) and [`references/positioning.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/positioning.md) provide additional constraints on prompt authoring and geometric alignment that the CLI enforces during execution.