ClisbotClisbot
View as markdown

Upgrade to v2

Clisbot v2 keeps the npm package clisbot, the clis command and the default home ~/.clisbot. It needs Node.js 22.19 or newer.

npm install -g clisbot@latest
npx --yes clisbot@latest onboard

npx makes sure the v2 CLI runs even if ~/.clisbot/bin/clisbot still points at the old install. For another home, add --home /absolute/path. Then open the printed pairing link, as in Getting started.

If systemd or launchd starts v1 for you, stop that service first so it cannot restart v1.

What happens to your old home

  • Backup: the v1 config, runtime state and temporary credentials are copied to a private folder under <home>/backups/.
  • Stop v1: only a process proven to be v1 in this home is stopped. If that cannot be proven, onboarding stops and v2 does not start. tmux sessions are left alone.
  • Config: v2 creates config.json if it is missing. The v1 clisbot.json is not changed. A valid config.json is kept as is; an invalid one is backed up and replaced.
  • Projects: your old agent folders are registered as Projects without changing their files. Code, MEMORY.md, SOUL.md, USER.md and other workspace files stay where they are.

<home>/v1-upgrade.json lists the backup, the stopped processes, the registered folders and what is left to do. It holds no tokens; the backup folder can, so keep it private.

Set up again

  • Slack, Telegram and Zalo: channels now live in the Hub, and v2 does not import the old setup. Run clisbot hub start, finish account setup, create a Connection with your existing token, set its Rules to the old groups, DMs and allowed people, then link the owner when asked.
  • Not converted: running tmux sessions, queued prompts, loops, runner arguments, custom provider environment settings and Zalo Personal logins.
  • History: import provider sessions with clisbot import where the provider supports it.
  • Instructions: workspace files that mention old CLI commands need editing by hand.

If something fails

  • Onboarding reports a handover failure: v2 has not started. Fix the process or file it names and run onboarding again.
  • v2 started but a later step failed: check clisbot status and <home>/daemon.log.
  • Back to v1: run clisbot daemon stop, install the old npm version, and restore the wrapper and credentials from the backup. Changes made in v2 do not carry back to v1.