# How to Start a New Instance of the CAD Viewer in text-to-cad

> Learn how to start a new instance of the CAD Viewer in text-to-cad using the cadgen viewer --new command or npm run dev for development. Access a fresh viewer or enable hot reload.

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

---

**Use the `cadgen viewer --new` command from your target directory to force a fresh instance, or run `npm run dev` in `apps/viewer` to launch a development server with hot reload.**

The text-to-cad repository by earthtojake combines a **React frontend** with a **Python backend** to provide an interactive CAD Viewer for local directories. Starting a new instance requires understanding the instance reuse logic that checks the current working directory and a version-derived identity token before binding to an available port.

## Understanding the CAD Viewer Architecture

The CAD Viewer is split into two components: a lightweight React client and a Python backend provided by the `cadgen.viewer` package. Each instance serves exactly one directory—identified by its real path—and is managed by a launcher that decides whether to attach to an existing server or spawn a new one.

The decision 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#L1-L34). When you invoke the viewer, the launcher checks for a running instance matching the current directory's real path and the version-derived identity token. If a match exists, it reuses that server; otherwise, it initializes a new one on the first available port greater than or equal to **3245**. For the full launch contract, see the [viewer README](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/README.md#L37-L70).

## Starting a New Instance

To explicitly create a fresh server rather than attaching to an existing one, append the `--new` flag to your command. This bypasses the reuse check and initializes a new Python backend immediately.

```bash
cd /path/to/models
cadgen viewer --new --host 127.0.0.1 --json

```

The `--json` flag outputs machine-readable JSON containing the `url` and `port`, enabling easy integration with automation scripts.

### Development Mode with Vite

For active development, navigate to `apps/viewer` and use the Vite development server. According to the [CLI implementation](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/viewer.py), this mode spawns a temporary Python backend on an ephemeral port and proxies API routes—including `/__cad` and `/__tess_cache`—to it automatically.

```bash
cd apps/viewer
npm run dev -- --host 127.0.0.1

```

The dev server compiles the React client on-the-fly—entry point at [[`apps/viewer/src/client/main.jsx`](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/src/client/main.jsx)](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/src/client/main.jsx)—and launches the backend without requiring a prior build step. Access the viewer at `http://127.0.0.1:5173/?file=<relative-path>`.

### Production Mode

For production, first build the static client bundle defined in [[`apps/viewer/package.json`](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/package.json)](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/package.json), then launch the viewer from the directory containing the built assets:

```bash
cd apps/viewer
npm run build
cd /path/to/serve
cadgen viewer --host 127.0.0.1

```

The `cadgen` CLI serves the pre-built `dist/` folder generated by the build command. The viewer binds to the first free port ≥ 3245 and prints the accessible URL upon startup.

## Managing Running Instances

You can inspect and terminate viewer processes using the CLI subcommands.

- **List instances**: `cadgen viewer list` displays all currently running servers and their ports.
- **Stop an instance**: `cadgen viewer stop --port <n>` terminates the server listening on the specified port number.

These commands allow you to clean up stale processes before starting a new instance with specific port requirements.

## Summary

- The CAD Viewer combines a React frontend and Python backend, serving a single directory per instance.
- Instance uniqueness is determined by the real path of the working directory and a version-derived identity token as implemented in [`main.py`](https://github.com/earthtojake/text-to-cad/blob/main/main.py).
- Use `cadgen viewer --new` to force a fresh instance and bypass the reuse logic.
- Development uses `npm run dev` in `apps/viewer` to enable hot reload and temporary backend spawning via Vite.
- Production requires running `npm run build` first, then executing `cadgen viewer` from the target directory.
- Manage running servers with `cadgen viewer list` and `cadgen viewer stop --port <n>`.

## Frequently Asked Questions

### How do I force a new CAD Viewer instance if one is already running?

Execute `cadgen viewer --new` from the directory you want to serve. This flag instructs the launcher to ignore any existing instance matching the current directory and create a fresh Python backend on the next available port.

### What port does the CAD Viewer use by default?

The viewer automatically selects the first free port greater than or equal to **3245**. You can override this behavior by passing the `--port` argument with your desired port number.

### Can I run the CAD Viewer from any directory?

Yes. The viewer serves the current working directory where the command is executed. For development, you must run `npm run dev` from `apps/viewer`. For production, run `cadgen viewer` from the directory containing your CAD files (and the built `dist/` folder if serving locally).

### How do I stop a running CAD Viewer instance?

Use the command `cadgen viewer stop --port <n>`, replacing `<n>` with the port number displayed when the server started. Alternatively, use `cadgen viewer list` to identify active ports before terminating them.