Migrations

Migrating from text-to-cad 0.8 to 0.10

A model's code does not change: a project that builds on 0.8 builds on 0.10, and from cadgen import model still works (cadgen is the library, cad, under its earlier name). What changes is the names around it. What you do by hand, and nothing more:

1. Run the install command again, then restart the apps it lists:

curl -fsSL https://texttocad.dev/install.sh | sh

On Windows, in PowerShell: irm https://www.texttocad.dev/install.ps1 | iex. It installs 0.10 in every agent app and the cad command, moves what 0.10 keeps of 0.8's state into its own folder (step 5), and stops 0.8's server with 0.8's own cadgen stop. Upgrading is a cutover: 0.10 never talks to anything of 0.8's, so an app still running the 0.8 plugin goes on with 0.8 alone until you restart it, and a CAD page left open from 0.8 needs a new link from your agent (step 7). A 0.8 server started again meanwhile keeps port 3245, and 0.10's serves on the next free port (3246) and says so; the next time 0.10's server starts with 3245 free (after cad stop, an update or a restart), it is back on 3245. An app that updates 0.8's plugin by itself (Codex fetches 0.8's catalog from GitHub) brings 0.10 without the install command: 0.10's server then runs beside 0.8's in the same way, until the install command stops 0.8's.

Each app's plugin now comes from a folder on your computer that the release writes, plugin in the new state folder (step 5), rather than from GitHub: the installer takes out the copy 0.8's put in each app -- Claude Code's and Codex's earthtojake catalog with its plugin, Gemini's extension, Cursor's clone -- and puts the folder's in its place: a local catalog, text-to-cad (text-to-cad@text-to-cad), in Claude Code and Codex, the folder linked in Gemini, a copy of it in Cursor (docs/install.md). Codex no longer fetches the repository each time it starts, and no app updates its plugin by itself. A plugin you installed by hand from GitHub goes the same way the next time the installer runs.

2. cadgen is cad in commands, with the same verbs and options: cadgen export <id> part.step is cad export <id> part.step, ~/.local/bin/cadgen is ~/.local/bin/cad (on Windows cad.exe; in 0.10 cad.cmd), and a skill's uvx ... --from cadgen==0.8.4 cadgen doctor is uvx --no-config --managed-python --python 3.14 --from cad-server==0.10.0 cad doctor. 0.8's cadgen command still runs 0.8, beside 0.10, until cad doctor --prune removes it.

3. CADGEN_* is CAD_* in environments, the rest of each name the same: CADGEN_TELEMETRY=0 is CAD_TELEMETRY=0, CADGEN_ENGINE_PORT is CAD_ENGINE_PORT, CADGEN_STATE_DIR is CAD_STATE_DIR. 0.10 reads no CADGEN_ name.

4. A hand-installed MCP command line -- an MCP config you wrote yourself, with uvx ... --from cadgen==0.8.4 cadgen mcp -- is the CAD app's own package now:

uvx --no-config --managed-python --python 3.14 --from cad-mcp==0.10.0 cad-mcp

The server's key stays cad. The installer rewrites the Claude Desktop entry it wrote (docs/install.md).

5. The state and cache folders moved, named cad now:

0.80.10
State, macOS~/Library/Application Support/cadgen~/Library/Application Support/cad
State, Linux~/.local/state/cadgen ($XDG_STATE_HOME)~/.local/state/cad
State, Windows%LOCALAPPDATA%\cadgen-state%LOCALAPPDATA%\cad-state
Cache~/.cache/cadgen ($XDG_CACHE_HOME; Windows %LOCALAPPDATA%\cadgen)~/.cache/cad (Windows %LOCALAPPDATA%\cad)

The installer moves into the new state folder, once, what 0.10 keeps: your settings (the telemetry answer, so a no stays a no -- the old folder keeps a no too, for 0.8 while it is still installed -- and the language), the documents' records and Recents, and setup's receipt. Recents is as it was. 0.8's page token stays behind, so a link 0.8 printed opens nothing in 0.10: ask your agent for a new one. The cache does not move: a model in Recents opens again once its script runs (cad run model.py), and the old cache folder can be deleted, as can the old state folder once nothing of 0.8 runs. A CAD_STATE_DIR you set names a folder that moves nowhere.

6. Updates come by themselves: the CAD server installs a newer release that breaks nothing once it is out (a patch release before 1.0, a patch or minor release from 1.0) and switches to it once nothing is running; one that may break something waits for you. cad update auto off (or Automatic updates in the menu under CAD's logo) leaves them all to you: the update button in the viewer and the CAD app, cad update, or the install command again.

7. The engine's HTTP API is /api/v1: a script that read the engine's port by hand reads GET /api/v1/server for 0.8's /__cad/server and /__cad/version, a document by its id at /api/v1/documents/<id> (its envelope, whose api names its kind's reads) for /__cad/catalog and /__cad/api/doc/<id>, and the rest as the engine's README lists it (Wire format). A CAD page left open from 0.8 stops working once 0.8's server stops: 0.10's never answers it, nor signs it in again, so ask your agent for a new link. The CAD tab in Codex or the card in Claude Desktop is 0.8's own app, which the restart the install command asks for replaces.

Installing the library into a Python of your own instead of the install command: it is cad on PyPI now (pip install 'cad[build123d]==0.10.0'; pin it, the release you run), beside the server, cad-server, and the CAD app's, cad-mcp; cadgen installs cad at the same release (cadgen[kernel], 0.8's spelling, as cad[build123d]).