How to Use text-to-CAD from the Bash Shell: A Complete CLI Guide

Install the text-to-CAD skill library via the Skills CLI and use the step, inspect, and snapshot scripts to generate, validate, and visualize CAD models directly from the terminal.

The text-to-CAD repository by earthtojake provides a command-line toolkit for generating precision CAD artifacts without leaving your terminal. This skills-based library integrates with the Skills CLI to deliver Python-driven workflows for creating STEP files, assemblies, and exports using build123d. Whether you are automating part generation or validating geometry, the Bash interface provides direct access to the entire pipeline as implemented in earthtojake/text-to-cad.

Installing text-to-CAD via the Skills CLI

The preferred entry point for Bash users is the Skills CLI, which pulls the generated skill runtimes directly from the repository's main branch. This installs the command-line tools and the CAD Viewer dependency in one step.

Run the following command to install the library:

npx skills install earthtojake/text-to-cad

This command configures the environment variables and shell aliases required to run the Python scripts located in the scripts/ directory. According to the repository README, this is the canonical installation method for CLI-managed environments.

Generating STEP Files from Python Scripts

The core generation workflow centers on the step script located at scripts/step. This tool accepts either a Python file containing build123d source code or an existing STEP file as input, producing a validated STEP artifact as output.

To generate a part from a Python script:

python scripts/step --kind part path/to/model.py --output my_part.step

The --kind parameter specifies the generation mode. Use part for single components or assembly for combined models. The script executes the gen_step() function defined in your Python file, which must return a build123d geometry object. If you omit output flags, the tool writes to a default location based on the input filename.

Inspecting and Validating Geometry

After generation, validate the geometry using the inspect script. This tool lists selector references, measures dimensions, and verifies positioning to ensure the model meets design specifications.

Run a comprehensive inspection with:

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

The refs subcommand analyzes the STEP file's topological references, while the flags --facts, --planes, and --positioning output dimensional data and coordinate system alignment. This step is critical for catching geometric errors before exporting to secondary formats.

Capturing Visual Snapshots

Every primary CAD output requires a visual snapshot for review. The snapshot script generates PNG or GIF renders of your STEP file for documentation and verification purposes.

Create a snapshot with:

python scripts/snapshot my_part.step

By default, this produces a PNG file in the same directory as the input STEP file. The snapshotting process is mandatory for primary artifacts according to the CAD skill specification documented in skills/cad/SKILL.md.

Launching the CAD Viewer

The text-to-CAD toolkit includes a browser-based CAD Viewer that launches via npm. The viewer automatically serves your generated models if it is not already running, returning a local URL for inspection.

Start the viewer from the repository root:

npm --prefix viewer run serve -- --host 127.0.0.1 --dir "$PWD/models"

The --dir parameter requires an absolute path to the directory containing your STEP or STL files. Once running, the viewer renders the geometry and provides interactive controls for examining the model. The viewer package logic is detailed in the repository's AGENTS.md file.

Exporting to Secondary Formats (STL, 3MF, GLB)

Once you validate the primary STEP file, generate secondary exports for manufacturing or visualization. The step script handles these conversions automatically when you supply the --export flag.

Export to STL format:

python scripts/step --kind part model.py --output part.step --export stl

Supported export formats include STL, 3MF, and GLB. The specific format availability and export parameters are documented in the supported-exports reference section of skills/cad/SKILL.md (lines 98-100). The secondary files appear in the same output directory as the primary STEP file.

End-to-End Bash Workflow Example

Below is a complete workflow that creates a rectangular block with holes, validates the geometry, and prepares it for viewing.

# Install the skill library (run once)

npx skills install earthtojake/text-to-cad

# Create a build123d source file

cat > model.py <<'PY'
from build123d import *
def gen_step():
    block = Box(100, 60, 20)
    holes = Cylinder(8, 30).translate((50, 30, 0))
    block = block.subtract(holes)
    return block
PY

# Generate the STEP file

python scripts/step --kind part model.py --output block.step

# Validate geometry and positioning

python scripts/inspect refs block.step --facts --positioning

# Create visual documentation

python scripts/snapshot block.step

# Launch the viewer (use absolute path)

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

For assembly workflows, create multiple part files, generate individual STEP files, then write an assembly script that uses AssemblyHelper from the cadpy package to combine them with joints before running the final step command with --kind assembly.

Summary

• Install text-to-CAD using npx skills install earthtojake/text-to-cad to configure the CLI environment.
• Generate models with python scripts/step --kind part <input.py> --output <file.step>.
• Validate geometry using python scripts/inspect refs <file.step> with flags for dimensional facts and positioning.
• Snapshot every primary output using python scripts/snapshot <file.step> to create PNG renders.
• View models by running npm --prefix viewer run serve with an absolute directory path.
• Export to STL, 3MF, or GLB by adding --export <format> to the step generation command.

Frequently Asked Questions

How do I install text-to-CAD without using npx?

The text-to-CAD library is designed as a skills-library for the Skills CLI ecosystem, and npx skills install earthtojake/text-to-cad remains the supported installation method. Manual installation would require cloning the repository, installing Python dependencies for build123d, and configuring the scripts/ directory paths manually, which bypasses the runtime environment management provided by the Skills CLI.

What Python function must my model file contain?

Your Python script must define a gen_step() function that returns a build123d geometry object. The scripts/step tool imports this function and executes it during the generation phase. For assemblies, use the AssemblyHelper class from the cadpy.assembly module to load existing STEP files and define joints before returning the combined geometry.

Why does the CAD Viewer require an absolute directory path?

The viewer's npm serve command uses the --dir argument to mount a static file server. Relative paths can resolve incorrectly depending on the npm execution context, so the documentation in AGENTS.md specifies using "$PWD/models" or another absolute path to ensure the viewer locates your STEP and STL files consistently across different shell sessions.

Can I convert existing STEP files to STL without modifying Python code?

Yes. The scripts/step utility accepts existing STEP files as input using the same --kind part flag. Run python scripts/step --kind part existing.stp --output new.step --export stl to generate the secondary STL format without writing additional Python code, provided the input file contains valid geometry that passes the inspection stage.

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