Updating & Uninstalling

Updating

Update to the latest version with a single command:

monoclaw update

This pulls the latest code, updates dependencies, and prompts you to configure any new options that were added since your last update.

What happens during an update

When you run monoclaw update, the following steps occur:

1. Pairing-data snapshot — a lightweight pre-update state snapshot is saved.
2. Git pull — pulls the latest code from the main branch and updates submodules
3. Dependency install — runs uv pip install -e ".[all]" to pick up new or changed dependencies
4. Config migration — detects new config options added since your version and prompts you to set them
5. Gateway auto-restart — running gateways are refreshed after the update completes so the new code takes effect immediately.

Preview-only: monoclaw update --check

Want to know if you're behind origin/main before actually pulling? Run monoclaw update --check — it fetches, prints your local commit and the latest remote commit side-by-side, and exits 0 if in sync or 1 if behind. No files are modified, no gateway is restarted.

Full pre-update backup: --backup

For high-value profiles (production gateways, shared team installs) you can opt into a full pre-pull backup of MONOCLAW_HOME:

monoclaw update --backup

Or make it the default:

# ~/.monoclaw/config.yaml
updates:
  pre_update_backup: true

Checking your current version

monoclaw version

Compare against the latest release at the GitHub releases page.

Updating from Messaging Platforms

You can also update directly from Telegram, Discord, Slack, WhatsApp, or Teams by sending:

/update

This pulls the latest code, updates dependencies, and restarts running gateways. The bot will briefly go offline during the restart (typically 5–15 seconds) and then resume.

Manual Update

If you installed manually (not via the quick installer):

cd /path/to/monoclaw-runtime
export VIRTUAL_ENV="$(pwd)/venv"

# Pull latest code and submodules
git pull origin main
git submodule update --init --recursive

# Reinstall (picks up new dependencies)
uv pip install -e ".[all]"
uv pip install -e "./tinker-atropos"

# Check for new config options
monoclaw config check
monoclaw config migrate   # Interactively add any missing options

Rollback instructions

If an update introduces a problem, you can roll back to a previous version:

cd /path/to/monoclaw-runtime

# List recent versions
git log --oneline -10

# Roll back to a specific commit
git checkout <commit-hash>
git submodule update --init --recursive
uv pip install -e ".[all]"

# Restart the gateway if running
monoclaw gateway restart

Uninstalling

monoclaw uninstall

The uninstaller gives you the option to keep your configuration files (~/.monoclaw/) for a future reinstall.

Manual Uninstall

rm -f ~/.local/bin/monoclaw
rm -rf /path/to/monoclaw-runtime
rm -rf ~/.monoclaw            # Optional — keep if you plan to reinstall

monoclaw gateway stop
# Linux: systemctl --user disable monoclaw-gateway
# macOS: launchctl remove ai.monoclaw.gateway