# Upgrade and uninstall

> How Tokenade updates itself every 24 hours, how to force or disable updates, and how tokenade uninstall removes hooks, data and the binary.

Source: https://tokenade.net/en/docs/upgrade-uninstall · Updated: 2026-10-16

Tokenade keeps itself up to date: you normally never run an upgrade by hand. When you want to leave, one command undoes everything it set up. This page covers both.

## Automatic updates

At most once every 24 hours, any `tokenade` invocation (a hook, a `wrap`, the status line) starts a background check. It looks up the latest release on [GitHub Releases](https://github.com/pi-infected/tokenade/releases) and, if a newer version exists, downloads it, verifies it, and swaps the binary atomically. Your agent keeps running; the next call uses the new version.

After the swap, the newly installed binary finishes the job itself: it restarts the local LLM proxies that were running the old version and rewrites the rules files Tokenade maintains for your agents. The options you passed to `tokenade install` (`--no-hook`, `--only`, `--no-debug-log`…) are kept across upgrades.

## Force or control updates

```bash
tokenade upgrade            # check now and install if newer
tokenade upgrade --check    # only print what is available, no swap
tokenade upgrade --off      # disable the background check (persistent)
tokenade upgrade --on       # re-enable it
```

`self-update` is an alias of `upgrade`. `--off` writes a marker file, `auto-update-off`, in `~/.tokenade/`. To skip the check for one session only, set `TOKENADE_NO_AUTO_UPDATE=1` in the environment.

On Windows, a running `.exe` cannot be overwritten, so the old binary is renamed to `.old` and replaced on the next start.

### Installs managed by a package manager

If the directory holding the binary is not writable by you (npm installed globally as root, Homebrew, a system package), the swap is refused with:

```text
binary parent dir … is not writable — likely a system-managed install (npm -g as root, Homebrew, apt, etc.). Update through that package manager instead (e.g. `npm update -g` / `brew upgrade tokenade`).
```

For an npm install, update with:

```bash
npm update -g @tokenade/cli
```

## Uninstall

```bash
tokenade uninstall --dry-run   # list everything that would be removed, change nothing
tokenade uninstall             # full removal
```

The full command runs seven steps, in this order:

1. Restores every MCP server that `tokenade mcp-wrap` wrapped to its original `command` and `args`. It runs first, so even a crashed uninstall leaves your MCP servers working.
2. Strips the fenced `<!-- tokenade:start -->` … `<!-- tokenade:end -->` block from `~/.claude/CLAUDE.md`, after taking a backup.
3. Removes the `tokenade` entry from `mcpServers` / `mcp` in every detected agent config.
4. Removes every hook group tagged `tokenade` from `~/.claude/settings.json`, and the same for other agents (Codex hooks and their trust entries, Cursor, Copilot, OpenCode, Kilo Code plugins…).
5. Removes the shell proxy from every shell rc file (`.bashrc`, `.zshenv`, `.zshrc`, `config.fish`, PowerShell, `.cshrc`…) and deletes the `~/.tokenade/shellproxy.*` fragments.
6. Deletes Tokenade's data: `~/.tokenade/` (savings ledger, databases, debug log) and `~/.cache/tokenade/` (stash, model). Only these two trees are removed, and symlinks are never followed out of them.
7. Handles the binary according to how it was installed:

| Installed with | What uninstall does |
|---|---|
| npm | Prints `npm uninstall -g @tokenade/cli` (npm owns the binary). |
| cargo | Prints `cargo uninstall tokenade-cli`. |
| Homebrew | Prints `brew uninstall tokenade`. |
| Standalone (`~/.local/bin`, `/usr/local/bin`) | Deletes the binary on Linux and macOS. On Windows, a running `.exe` cannot delete itself, so it prints the `del` command. |

The command is idempotent: running it again after a clean uninstall does nothing. If you installed the LLM proxy, uninstall also points each agent back at its original provider address and removes the proxy's start-at-boot entries.

### Flags and partial removal

| Command | Effect |
|---|---|
| `tokenade uninstall --keep-data` | Steps 1–5 and 7, but keeps `~/.tokenade` and `~/.cache/tokenade`, so your savings history survives a reinstall. |
| `tokenade uninstall --headless` | Integration and data removal with no banner and no guidance, and never touches the binary. Used by npm's `preuninstall` hook. |
| `tokenade uninstall aliases` | Removes **only** the shell proxy (step 5). Hooks, MCP wiring, `CLAUDE.md` and your data stay. Also accepted: `alias`, `shell-proxy`, `shellproxy`. |
| `tokenade unwrap-mcps` | Runs only step 1. |

If you uninstall through npm (`npm uninstall -g @tokenade/cli`), npm's `preuninstall` hook runs `tokenade uninstall --headless` first, so the agent integrations and the data directories are removed along with the package.

### Secrets in caches

If credentials may have been captured in Tokenade's caches, run `tokenade scrub-cache` before uninstalling, or `tokenade scrub-secret <substring>` for a specific leaked string. With a full uninstall, both trees are deleted anyway.

## Reinstall

```bash
npm install -g @tokenade/cli
tokenade install
```

`tokenade install` reuses the options remembered in `~/.tokenade/install-options.json` if you kept your data; pass `--defaults` to start from scratch. See [Install Tokenade](https://tokenade.net/en/docs/install).

## Related

- [Install Tokenade](https://tokenade.net/en/docs/install)
- [Files and paths](https://tokenade.net/en/docs/files-and-paths)
- [Changelog](https://tokenade.net/en/docs/changelog)
- [Troubleshooting](https://tokenade.net/en/docs/troubleshooting)
