How to Use the CAD Viewer to Preview Files in text-to-cad

Launch the CAD Viewer with cadgen viewer --json from your model workspace directory, then open the returned URL with a ?file= query parameter pointing to your CAD file relative to that directory.

The CAD Viewer in the earthtojake/text-to-cad repository provides a local HTTP server and React client for previewing STEP, GLB, STL, and other 3D formats directly in your browser. This guide explains how to start the viewer, construct preview URLs, and manage running instances according to the source code in the cadgen package.

Architecture of the CAD Viewer

The CAD Viewer consists of three tightly integrated components: a Python backend server, a command-line interface, and a static React client.

Backend Server Implementation

The backend is a lightweight HTTP server implemented in [packages/cadgen/src/cadgen/viewer/main.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py). It handles port allocation, instance reuse logic, and serves the pre-built client assets. You can also invoke the server directly via python -m cadgen.viewer using the entry point defined in [packages/cadgen/src/cadgen/viewer/__main__.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/__main__.py).

The server exposes routes for artifact retrieval under /__cad and /__tess_cache, enabling the client to load compiled geometry.

CLI Front-End

The primary interface is the cadgen viewer command, implemented in [packages/cadgen/src/cadgen/cli/viewer.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/viewer.py). This module parses arguments and forwards them to the backend. Auxiliary commands for lifecycle management reside in [packages/cadgen/src/cadgen/cli/viewer_list.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/viewer_list.py) and [packages/cadgen/src/cadgen/cli/viewer_stop.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/viewer_stop.py), providing cadgen viewer list and cadgen viewer stop functionality.

Static React Client

The visual front-end is a React application built from the JavaScript workspace in apps/viewer. The bundling script [scripts/bundle/cadgen-runtime.sh](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/cadgen-runtime.sh) packages this client, which the backend then serves unconditionally to provide the interface for file browsing and 3D rendering.

Launching the CAD Viewer

You must launch the viewer from the directory containing your CAD files, as the server treats the current working directory as the served workspace.

Basic Launch and URL Capture

To start the server and obtain the preview URL, run:

cd models
cadgen viewer --json

The --json flag instructs the server to output a single JSON line containing the connection details:

{"url":"http://127.0.0.1:3245","port":3245,"action":"started"}

Capture this output to extract the base URL for constructing file-specific preview links.

Instance Reuse and Port Control

By default, the viewer attempts to reuse an existing instance if the launch directory and viewer binary match. To force a fresh instance, use the --new flag:

cadgen viewer --new --json

To bind to a specific port and disable reuse logic, specify --port:

cadgen viewer --port 8080 --json

You can also bind to a specific network interface using --host (default is 127.0.0.1):

cadgen viewer --host 0.0.0.0 --json

Constructing CAD Preview URLs

Once the server is running, you construct preview URLs by appending a file query parameter to the base URL returned by the --json output.

Relative Path Requirements

The file parameter must specify the path relative to the launch directory. For example, if you launched from the models/ directory and want to preview a STEP file located at gripper/STEP/gear_rack_gripper.step, the URL becomes:

http://127.0.0.1:3245/?file=gripper/STEP/gear_rack_gripper.step

The server scans the launch directory recursively, so the file browser in the viewer lists every artifact under that directory.

Supported File Formats

According to the source code in [skills/cad-viewer/SKILL.md](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md), the viewer supports STEP, GLB, STL, DXF, URDF, SRDF, and SDF artifacts.

Managing Viewer Instances

The CLI provides utilities for listing and terminating running instances.

Listing Active Viewers

To see all running CAD Viewer instances, their ports, and launch directories:

cadgen viewer list

Add --json for machine-readable output:

cadgen viewer list --json

Stopping a Specific Instance

To terminate a viewer listening on a specific port:

cadgen viewer stop --port 3245

Complete Workflow Example

The following workflow demonstrates installing dependencies, launching the viewer, and opening a specific CAD file:

# Install runtime dependencies

python -m pip install -r skills/cad-viewer/requirements.txt

# Verify cadgen installation

cadgen doctor .

# Navigate to your model workspace

cd models

# Launch viewer and capture URL

cadgen viewer --host 127.0.0.1 --json > launch.json

# Extract URL and construct preview link

URL=$(jq -r .url launch.json)
FILE="gripper/STEP/gear_rack_gripper.step"

# Open preview in browser

xdg-open "${URL}/?file=${FILE}"

Summary

• Launch from the correct directory: The CAD Viewer serves files relative to the current working directory where you invoke cadgen viewer.
• Use --json to capture the URL: This flag returns the port and base URL needed to construct preview links.
• Construct URLs with ?file=: Append the relative file path to the base URL to preview specific STEP, GLB, STL, or other supported formats.
• Manage instances via CLI: Use cadgen viewer list to see active servers and cadgen viewer stop --port <n> to terminate them.
• Key source files: Backend logic resides in [packages/cadgen/src/cadgen/viewer/main.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py), while the CLI implementation is in [packages/cadgen/src/cadgen/cli/viewer.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/viewer.py).

Frequently Asked Questions

What directory should I launch the CAD Viewer from?

You should launch the viewer from the directory you consider your model workspace, typically a models/ folder containing your CAD files. The server treats this launch directory as the root for all file serving and path resolution, as implemented in [packages/cadgen/src/cadgen/viewer/main.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py). Launching from the wrong directory (such as inside the skill's own folder) will serve the wrong files.

How do I preview a file located outside the launch directory?

The CAD Viewer only serves files within the launch directory tree. To preview an external file, either move it into the workspace directory or launch a new viewer instance from the directory containing the target file. The file parameter in the URL must be a relative path from the launch directory to the artifact.

Can I run multiple CAD Viewer instances simultaneously?

Yes, but you must specify different ports using the --port flag for each instance. Without this flag, the viewer attempts to reuse an existing instance if the launch directory and binary match. To force separate instances, use cadgen viewer --port 3245 --json and cadgen viewer --port 3246 --json from different directories or with different ports.

What file formats does the CAD Viewer support?

According to the [skills/cad-viewer/SKILL.md](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md) documentation, the viewer supports STEP, GLB, STL, DXF, URDF, SRDF, and SDF file formats. The React client in apps/viewer renders these formats using the artifact endpoints provided by the backend server.

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