How to Run text-to-CAD from the Command Line: Skills CLI Guide

Run text-to-CAD by installing the Skills CLI and invoking npx skills run <skill> <source.py> to generate STEP, URDF, or DXF files from Python generator functions.

The earthtojake/text-to-cad repository ships as a Skills plugin rather than a standalone executable. After installing the lightweight Node-based Skills CLI, the plugin registers sub-commands that invoke skill-specific scripts—such as cad, urdf, and dxf—to convert Python generator scripts into industry-standard CAD artifacts.

Install the Skills CLI and text-to-CAD Plugin

Before generating files, install the universal Skills CLI and register the text-to-cad plugin.

The Skills CLI is a minimal Node-based wrapper that loads plugins from npm or local clones. Install the plugin with:

npx skills install earthtojake/text-to-cad

This command pulls the plugin from the repository and registers its command set. Once installed, the CLI exposes sub-commands for each supported format.

Generate CAD Files from the Command Line

Each skill provides its own CLI module under skills/<name>/scripts/<name>/cli.py that parses argv, loads your Python generator, and writes the artifact. The standard invocation pattern is:

npx skills run <skill> <source_file>[=output_file]

Generate STEP Models

To create a STEP file from a Python script containing a gen_step() function, invoke the CAD skill:

npx skills run cad step my_part.py

This command executes skills/cad/scripts/step/cli.py, calling main() → generate_step_targets(). By default, it writes my_part.step to the current directory and prints the absolute path. Specify an explicit output path using the source-output pair syntax:

npx skills run cad step my_part.py=custom_name.step

Generate URDF Robot Descriptions

For robotics applications, generate URDF files using the URDF skill. In skills/urdf/scripts/urdf/cli.py, the main() function handles argument parsing and delegates to generate_urdf_targets().

Run with automatic output naming:

npx skills run urdf my_robot.py

# Creates my_robot.urdf

Or specify the destination explicitly:

npx skills run urdf my_robot.py=robot.urdf

Under the hood, the CLI executes the following pipeline:

1. Target resolution: _resolve_target_specs() parses SOURCE=OUTPUT pairs or infers the .urdf suffix from the source filename.
2. Module loading: _load_generator_module() uses importlib.util to import your script as a temporary module, isolating it from the current Python path.
3. Generation: _generate_target_inner() calls your gen_urdf() function and validates its zero-argument signature.
4. Normalization: _normalize_urdf_payload() accepts XML elements, raw XML strings, or dict envelopes ({"xml": …}) for flexibility.
5. Persistence: _write_urdf_payload() creates the output directory, writes the file, and invokes track_generation_run() from cadpy_metadata to record provenance.

Generate DXF Drawings

The same architectural pattern applies to 2D DXF generation:

npx skills run dxf my_drawing.py

This invokes skills/dxf/scripts/dxf/cli.py, which processes your gen_dxf() function and outputs the drawing using the internal _write_dxf_payload() implementation.

Run Skills Without the Node Wrapper

For CI/CD pipelines or pure-Python environments, bypass the Skills CLI and invoke the Python modules directly.

Execute a skill CLI module using Python's module runner:

python -m skills.urdf.scripts.urdf.cli my_robot.py

Alternatively, import the generation functions programmatically:

from skills.urdf.scripts.urdf.cli import generate_urdf_targets

generate_urdf_targets(["my_robot.py"])

Both approaches execute the same internal functions—_load_generator_module(), payload normalization, and _write_urdf_payload()—without requiring Node.js.

Summary

• Install once: Run npx skills install earthtojake/text-to-cad to register the plugin with the Skills CLI.
• Command syntax: Use npx skills run <skill> <source> where skill is cad, urdf, dxf, or srdf.
• Output control: Specify source.py=output.ext or rely on default extensions inferred by _resolve_target_specs().
• Direct Python: Import from skills.<module>.scripts.<module>.cli to execute generators without the CLI wrapper.
• Isolation: The CLI loads generators via importlib.util to prevent path pollution and tracks metadata via track_generation_run().

Frequently Asked Questions

Do I need Node.js installed to use text-to-CAD?

Yes, the Skills CLI requires Node.js to run the npx commands that manage plugins and dispatch to skill scripts. However, you can invoke the underlying Python modules directly using python -m if you need to avoid Node.js in production environments.

What Python function must my generator scripts define?

Each skill expects a specific zero-argument function. For URDF generation, define gen_urdf(); for STEP files, define gen_step(); for DXF, define gen_dxf(). The _generate_target_inner() function validates these signatures at runtime and raises errors if the required function is missing or accepts arguments.

Can I output files to custom directories?

Yes, include the directory path in the output specification. For example, npx skills run urdf robot.py=./build/robot.urdf places the file in the build directory. The _write_urdf_payload() function automatically creates output directories if they do not exist.

How does the CLI handle dependencies in my generator scripts?

The _load_generator_module() function imports your script as a temporary module, but you must ensure all dependencies are available in your Python environment. The CLI does not manage virtual environments or install packages, so install requirements like cadquery or build123d before invocation.

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