How to Integrate text-to-CAD into Other Applications: 3 Methods Explained

You can integrate text-to-CAD into other applications via CLI commands that accept JSON input, direct Python API calls using the cadpy package, or an HTTP/JSON microservice with an embedded viewer.

The earthtojake/text-to-cad repository provides a skills-based architecture for generating CAD, robot-description, and G-code artifacts. Whether you are building a web service, desktop application, or automation pipeline, you can embed text-to-CAD functionality by choosing the integration method that matches your technology stack. The codebase organizes functionality into three layers—Skills (CLI entry points), Packages (reusable Python/JS libraries), and Viewer (web UI)—each offering distinct integration points.

Overview of the Architecture

The repository structure separates concerns into portable components:

• Skills (skills/): Command-line tools that generate STEP, STL, 3MF, GLB, URDF, SRDF, SDF, DXF, and G-code files
• Packages (packages/): Runtime libraries including cadpy (Python geometry processing), cadjs, and implicitjs
• Viewer (viewer/): Optional web UI for previewing generated assets

Integration occurs at three boundaries: CLI invocation, direct Python import, or HTTP service.

Method 1: CLI-Based Integration

The most portable approach invokes the skill via command line. All skills expose a run entry point that reads JSON from stdin and writes results to stdout, making them compatible with any language that can spawn subprocesses.

Install the skill once per host:

npx skills install earthtojake/text-to-cad

Prepare a JSON request and execute the CAD skill:

cat <<EOF > request.json
{
  "prompt": "Create a 100 mm × 60 mm × 20 mm block with four 8 mm vertical holes",
  "output": "step"
}
EOF

npx skills run cad < request.json > response.json

The CLI generates the STEP file, stores it under models/, and returns a JSON payload containing the artifact path. The parsing and dispatch logic resides in skills/cad/scripts/step/cli.py, which handles the JSON validation and routes to the appropriate generator.

Method 2: Direct Python API Integration

For Python-based host applications, bypass the CLI overhead by importing the shared cadpy package directly. The library is vendored into each skill at build time to ensure version consistency.

Install the package from the repository root:

pip install .

Then generate geometry programmatically:

from pathlib import Path
from cadpy.generation import generate_mesh
from cadpy.step_artifact import export_shape_stl
from cadpy.step_scene import _create_cuboid

# Create a cuboid with holes using OpenCascade (OCC) primitives

cuboid = _create_cuboid(
    size=(0.1, 0.06, 0.02), 
    holes=[{'diameter': 0.008, 'axis': 'Z'}]
)

# Generate mesh with default tolerances

mesh = generate_mesh(cuboid)

# Export to STL format

stl_path = export_shape_stl(mesh, target_path=Path("my_block.stl"))
print(f"STL written to {stl_path}")

Key implementation files include:

• packages/cadpy/src/cadpy/generation.py – Mesh generation logic
• packages/cadpy/src/cadpy/stl.py – STL export routines
• packages/cadpy/src/cadpy/step_scene.py – Geometry construction helpers

Method 3: HTTP/JSON Service with Embedded Viewer

For applications requiring real-time preview, launch the CAD viewer as an HTTP service. The viewer serves a web UI bound to a models/ directory and can be embedded in Electron, QtWebEngine, or browser iframes.

Launch the server from your application code:

import subprocess
import time
import webbrowser

# Start the viewer on an auto-selected port

proc = subprocess.Popen([
    "npm", "--prefix", "viewer", "run", "serve",
    "--", "--host", "127.0.0.1", "--dir", "/abs/path/to/models"
])

time.sleep(2)  # Allow server startup

# URL is emitted by the server; open for preview

url = "http://127.0.0.1:4178/?dir=/abs/path/to/models"
webbrowser.open(url)

# Cleanup when application exits

proc.terminate()

The server implementation in skills/cad-viewer/scripts/viewer/moveit2_server/moveit2_server/server.py handles directory serving and WebSocket communication for model updates.

Packaging for Distribution

When shipping an application that depends on text-to-CAD, pin the version referenced in the VERSION file (0.3.13 at time of writing) and bundle the skill outputs.

Create a self-contained artifact:

scripts/bundle/bundle.sh --skill cad

This generates a dist/ folder containing compiled JavaScript, generated models, and runtime assets ready for inclusion in your installer. The bundling logic is defined in scripts/bundle/bundle.sh.

Summary

• CLI integration works across all languages by passing JSON via stdin/stdout to npx skills run cad
• Python API integration requires importing cadpy and calling functions like generate_mesh() and export_shape_stl() directly
• HTTP service integration launches the viewer from skills/cad-viewer to provide web-based previews of generated assets
• Distribution requires pinning version 0.3.13 and using scripts/bundle/bundle.sh to create portable packages

Frequently Asked Questions

What input format does the text-to-CAD CLI expect?

The CLI expects JSON input with at minimum a prompt string and an output format field (e.g., step, stl, or urdf). The JSON is read from stdin by the handler in skills/cad/scripts/step/cli.py, which validates the schema before dispatching to the generator.

Can I use text-to-CAD without installing Node.js?

Yes. While the CLI entry points use npx, you can integrate directly via the Python API by installing the cadpy package from packages/cadpy. This approach requires only Python and the underlying OpenCascade dependencies, bypassing the Node.js runtime entirely.

How do I preview generated CAD files in my application?

Launch the viewer service via the script in skills/cad-viewer/scripts/viewer/moveit2_server/moveit2_server/server.py, which serves a web UI on a local port. Point the server to your models/ directory absolute path, then embed the resulting URL in a webview or browser component.

What version of text-to-CAD should I pin for production?

Pin version 0.3.13 as specified in the repository's VERSION file. Use the scripts/bundle/bundle.sh script to create reproducible builds that include all runtime assets, ensuring consistent behavior across deployment environments.

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