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

> Learn how to use the CAD viewer to preview files in text-to-cad. Launch the viewer with cadgen viewer --json and open the URL with a file query parameter to see your CAD files.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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](https://github.com/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)](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)](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)](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)](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)](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`](https://github.com/earthtojake/text-to-cad/tree/main/apps/viewer). The bundling script [[`scripts/bundle/cadgen-runtime.sh`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash
cd models
cadgen viewer --json

```

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

```json
{"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:

```bash
cadgen viewer --new --json

```

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

```bash
cadgen viewer --port 8080 --json

```

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

```bash
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)](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:

```bash
cadgen viewer list

```

Add `--json` for machine-readable output:

```bash
cadgen viewer list --json

```

### Stopping a Specific Instance

To terminate a viewer listening on a specific port:

```bash
cadgen viewer stop --port 3245

```

## Complete Workflow Example

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

```bash

# 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)](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)](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)](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)](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`](https://github.com/earthtojake/text-to-cad/tree/main/apps/viewer) renders these formats using the artifact endpoints provided by the backend server.