---
name: "cad-viewer"
description: "Start CAD Viewer and return review links for explicit CAD, implicit CAD, robot-description, and G-code files. Use when visually reviewing \u0060.step\u0060, \u0060.stp\u0060, \u0060.implicit.js\u0060, \u0060.implicit.mjs\u0060, \u0060.glb\u0060, \u0060.stl\u0060, \u0060.3mf\u0060, \u0060.gcode\u0060, \u0060.dxf\u0060, \u0060.urdf\u0060, \u0060.srdf\u0060, or \u0060.sdf\u0060 files, especially when handed off from CAD, implicit-cad, G-code, URDF, SRDF, or SDF generation skills."
license: "MIT"
metadata:
  dev.v-san.skills: |-
    origin: "https://github.com/earthtojake/text-to-cad"
    version: "1.1"
    changeDate: "2026-08-12"
    requires:
      dependencies:
        - "Node.js 20 or later"
        - "Python 3.12 or later for STEP and robot-description backends"
        - "Optional: ROS 2 and MoveIt2 for interactive planning controls"
    upstream:
      changeDate: "2026-07-10"
      commit: "fdbb4b4fb62d95ae298cfe9a46fdc7092bdaf423"
      path: "skills/cad-viewer"
      repository: "https://github.com/earthtojake/text-to-cad"
      version: "0.3.9"
---

# CAD Viewer

Provenance: maintained in [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad).
Use the installed local skill files as the runtime source of truth; the
repository link is only for provenance and release review.

Use this skill to open existing or newly generated CAD, implicit CAD,
robot-description, DXF, or plain FDM G-code files in CAD Viewer and hand back
live review links. The expected input is one or more explicit file paths.

## Start Viewer

Start one local CAD Viewer with the `start` package script, passing the absolute
artifact directory as `--dir`. This vendored snapshot does not contain the
upstream `agent:start` reuse launcher; do not call or claim that missing command.
The bundled server defaults to `127.0.0.1:4178`, supports an explicit `--port`,
and prints its listening URL. Keep the long-running process in its execution
session and use that URL for review links.

Choose `--dir` as the absolute directory that contains the model
artifacts and sidecars, commonly `<repo>/models` or the consuming project's
equivalent model directory. The `file=` value must be relative to that `--dir`.
If port 4178 is already occupied, first identify whether it is a suitable
Viewer. Reuse it only after its server endpoint confirms the intended directory;
otherwise choose an unused loopback port explicitly.

Run from this skill directory:

```bash
npm --prefix scripts/viewer run start -- --host 127.0.0.1 --dir <absolute-model-root>
```

Use the printed Viewer URL and append `file=`:

```bash
http://127.0.0.1:4178/?dir=/absolute/project/models&file=path/to/model.step
```

In sandboxed agent environments, local binding failures such as `EPERM` or
`EACCES` can occur; report the infrastructure failure rather than describing it
as a model-validation result.

## Links

- Before returning any `file=` link, resolve `<dir>/<file>` and confirm the
  artifact exists. Pass the generated artifact (e.g. `.step`), not its
  generator source (e.g. `.py`). If the resolved path is missing, do not
  return the link, and instead report the problem and point to the correct
  generated artifact path.
- Return one Viewer URL per requested file.
- Start the Viewer once per absolute directory `--dir`, then append
  `file=<path>` for each requested file. The file path must be relative to
  `--dir`.
- For directory-only review links, return the server URL with the `?dir=` value
  and no `file=` value.
- Do not stop an existing Viewer server unless the user asks.
- If Viewer startup fails, report the failure and continue with the owning skill's non-GUI validation or artifacts.

## Preview clients

The bundled server has no `--json` startup output. Parse the human-readable
`CAD Viewer backend listening on ...` line or use the explicit host and port,
then confirm `GET /__cad/server` returns HTTP 200 before handing the URL to a
browser or preview client.

## References

- Read `references/development.md` when the user asks to modify, debug, or
  iterate on CAD Viewer source.
- Read `references/viewer-features.md` when you need supported file types, Viewer controls, or file-specific feature details.
- Read `references/moveit2-server.md` only when the user specifically needs optional SRDF MoveIt2 IK or path-planning controls.