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 | shOn 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-mcpThe 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.8 | 0.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]).