Upgrade and uninstall
Updated
tokenade upgrade forces it, tokenade upgrade --off disables it. tokenade uninstall undoes every agent integration, deletes ~/.tokenade and ~/.cache/tokenade, and removes or tells you how to remove the binary. Preview it with --dry-run.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 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
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:
For an npm install, update with:
Uninstall
tokenade uninstall # full removal
The full command runs seven steps, in this order:
- Restores every MCP server that
tokenade mcp-wrapwrapped to its originalcommandandargs. It runs first, so even a crashed uninstall leaves your MCP servers working. - Strips the fenced
<!-- tokenade:start -->…<!-- tokenade:end -->block from~/.claude/CLAUDE.md, after taking a backup. - Removes the
tokenadeentry frommcpServers/mcpin every detected agent config. - Removes every hook group tagged
tokenadefrom~/.claude/settings.json, and the same for other agents (Codex hooks and their trust entries, Cursor, Copilot, OpenCode, Kilo Code plugins…). - Removes the shell proxy from every shell rc file (
.bashrc,.zshenv,.zshrc,config.fish, PowerShell,.cshrc…) and deletes the~/.tokenade/shellproxy.*fragments. - 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. - 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
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.