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

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 and 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:

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:

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:

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:

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:

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.

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 – Defines the core CAD skill contract including non-negotiable requirements that STEP is the canonical artifact and snapshots are mandatory.
• skills/urdf/SKILL.md – Specifies URDF robot description generation and validation protocols.
• 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 – 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. 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 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 file contains the primary contract including non-negotiables, while references/cad-brief.md and references/positioning.md provide additional constraints on prompt authoring and geometric alignment that the CLI enforces during execution.

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