# 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...

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:

```bash
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](https://www.texttocad.dev/docs/install)).
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](https://www.texttocad.dev/docs/install)).

**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]`).

