CAD Viewer Launcher

CAD Viewer

Provenance: maintained in 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. If the user asks to modify, debug, or iterate on CAD Viewer source itself, that is the repository's work, not this skill's — this skill runs the Viewer, it is not where you edit it.

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

Setup

The Viewer is part of cadgen: install this skill's requirements.txt into a Python >= 3.11 and the cadgen command carries the server and the prebuilt client. There is nothing else to install and no Node at run time.

python -m pip install -r requirements.txt

cadgen doctor <this skill's directory> confirms the installed cadgen matches the version this skill was published against.

Start Viewer

Launching is unconditional: the command below always ends with the URL of a live Viewer for the launch directory. If one is already running for that directory with the same Viewer code on disk (the reuse key is realpath(directory) x an identity token — the cadgen version salted with the Viewer files' newest mtime, so an upgraded Viewer never hands back a stale instance), its URL is returned ("action": "reused"); otherwise a new server starts on the first free port from 3245 upward ("action": "started"). Never pick or reason about ports — read the URL the command prints. Each instance serves ONE directory — the directory it is launched from — fixed for the life of the process. There is no flag for it: the cwd IS the served directory.

The base port 3245 is 0xCAD — "CAD" in hexadecimal.

cd /absolute/project/models && cadgen viewer --host 127.0.0.1 --json

(cadgen must be the one installed from this skill's requirements.txt. If it is not on PATH, python -m cadgen.viewer with that interpreter is the same launcher.)

Choose the launch directory deliberately — it is the whole ballgame. The cwd decides what the catalog SCANS (a project root drags in node_modules, .git and build output) and it is the instance REUSE key, so launching from wherever you happen to be can hand back a Viewer serving somewhere else. cd to the directory the user thinks of as their model workspace — usually the project's models/ directory — and launch from there. Never launch from inside this skill's directory: that serves the skill, not the models.

Flags: --json prints the machine-readable last stdout line ({"url", "port", "action": "started"|"reused"}) — always pass it and take the URL from there. --new forces a fresh instance instead of reusing. An explicit --port <n> is strict — "this port or fail" — and disables both reuse and rolling. cadgen viewer --help lists the rest.

URL shape

The page is the bare origin, and file= selects one artifact inside the served root:

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

The file= value is relative to the served directory. Nothing about the directory appears in the URL, so the same link means different files under different instances — the root is the server's, not the link's.

The launch directory is the workspace, not the file's folder. The Viewer scans it recursively, so the file browser lists every model beneath it and the user can switch files without a new link. Launch from the directory the user thinks of as their model workspace — typically the project's models/ directory, or the nearest common parent of the files you were asked to review — and put the rest of the path in file=. Launching from the artifact's own deep folder (cd .../models/gripper/STEP, ?file=gear_rack_gripper.step) opens the same model but hides the rest of the project, which is almost never what the user wants.

Port collisions are not your problem: the launcher rolls to a free port and the URL it prints is the truth. In sandboxed agent environments, local binding failures such as EPERM/EACCES can still occur; rerun with the needed permission/escalation.

cadgen viewer list shows every running instance with the directory it serves; cadgen viewer stop --port <n> ends one. (Both run from anywhere — only launching cares about the cwd.) To review a directory outside the current root, just cd there and launch again — reuse-or-start makes the second launch cheap and correct.