Skip to content
CommandChain CommandChain CommandChain Docs

Update or uninstall

The CommandChain app keeps itself up to date. Every command on this page runs on the computer itself, as the user who installed the app. The command is called commandchain-runner; it is the CommandChain app.

Installer options

Section titled “Installer options”

The install command takes options, for example to uninstall. Here is how to pass one:

Options go after sh -s --. For example, with --status:

Terminal window
curl -fsSL https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.sh | sh -s -- --status

Automatic updates

Section titled “Automatic updates”

Automatic updates are on by default, on macOS, Linux and Windows, from version 0.15.0. You do not need to do anything to stay up to date. If a computer has 0.14.0 or earlier (check with commandchain-runner version), run the install command again once, as shown in Install a specific release. After that it updates itself.

About 2 minutes after CommandChain starts, and then every 4 hours, it:

  1. Checks for a new release.
  2. Downloads it, checks it against its published checksum and checks that the new version starts.
  3. Waits until nothing is in progress: no agent turn running, no approval or question waiting for you, and no message on its way.
  4. Restarts into the new version.

Your sessions reconnect by themselves after the restart. Nothing you are working on is interrupted, because CommandChain waits for a quiet moment first.

Some things it never does:

  • It never installs a prerelease.
  • It never installs an older version than the one you have.
  • It updates only the app installed by the install command. A copy you run from somewhere else, or one managed by a package manager, does not update itself.

If a new version does not stay up

Section titled “If a new version does not stay up”

If a new version fails to start 3 times in a row without staying up for 2 minutes, CommandChain goes back to the version you had before, by itself. It does not install that failed version automatically again. A later release installs as usual.

Turn automatic updates off

Section titled “Turn automatic updates off”

Run this on the computer:

Terminal window
commandchain-runner update --auto off

To turn them back on, run commandchain-runner update --auto on. The background app picks up the change at its next check, without a restart.

You can also turn them off in two other ways:

  • Set the environment variable COMMANDCHAIN_AUTO_UPDATE to 0, false, off or no (1, true, on or yes turns them on). It wins over the --auto setting. See Environment variables.
  • Pass --no-auto-update to commandchain-runner or commandchain-runner sessions-connect. It applies only to that run.

Update now

Section titled “Update now”

To see whether a new version is out:

Terminal window
commandchain-runner update --check

It says “CommandChain <version> is up to date.” or “CommandChain <version> is available. You have <version>.” (text in angle brackets is filled in by your computer).

To install the new version now:

Terminal window
commandchain-runner update

It downloads and checks the new version, then says “Updated CommandChain to <version>.” The background app switches to it at its next quiet moment, the same way as an automatic update. If automatic updates are off, it tells you to restart the background app instead, and prints the command for it.

If this copy cannot update itself, it says so and prints the install command to run instead.

Update when the web app asks you to update CommandChain on a computer, for example Notes need a newer version on a computer, or “Update CommandChain on this computer and reconnect it to use automatic approval.” If commandchain-runner says “An older CommandChain background app is installed on this computer”, it means the same thing.

Install a specific release

Section titled “Install a specific release”

Running the install command again also updates CommandChain:

Terminal window
curl -fsSL https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.sh | sh

It replaces the app, keeps this computer’s connection and restarts the background app right away, which can interrupt a session that is working. You do not approve a new code; the installer prints ”✔ Already paired with CommandChain (saved pairing reused).”

To install a specific release instead of the latest, pass its version with the version option: --version <version> on macOS and Linux, -Version <version> on Windows, for example --version v0.14.0. The commands with options are under Installer options. The release notes list the versions. To stay on an older release, turn automatic updates off first, or CommandChain updates it again at its next check.

Check the version

Section titled “Check the version”
  • commandchain-runner version prints the version.
  • commandchain-runner status shows whether the app is running and connected.
  • The installer’s status option shows what is installed, the background app and the log file. The commands are under Installer options.

Disconnect without uninstalling

Section titled “Disconnect without uninstalling”

commandchain-runner logout deletes this computer’s connection and stops the background app, so the computer goes Offline. Text in angle brackets is filled in by your computer. When the background app was running, the output looks like this:

Terminal window
Disconnected this computer from <server>.
Stopped the background app, so this computer goes offline in CommandChain.
Remove it on the Computers page to take it off the list: <link>

Other things it can say:

  • “This computer has no saved connection to <server>.” There was nothing to disconnect.
  • “Could not stop the background app, so this computer still shows as online.” Stop it yourself, see Keep the CommandChain app running.
  • “CommandChain is still running on this computer (pid <pid>) with the old pairing”. It runs in a terminal window. Press Ctrl-C in that window to stop it.

To connect it again, run commandchain-runner in a terminal on that computer, and follow what it shows. You approve a new code, and the computer gets a new card on Computers.

Uninstall

Section titled “Uninstall”

  1. If you connected Claude Code sessions from your terminal, remove the Claude Code plugin while the app is still installed, because the uninstall does not remove it:

    Terminal window
    commandchain-runner claude-integration uninstall

    If you never did, or you already uninstalled the app, skip this step.

  2. Uninstall the app:

    Terminal window
    curl -fsSL https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.sh | sh -s -- --uninstall

This removes the program and the background app. It keeps this computer’s connection, so installing again later reconnects without a new code. It does not remove your coding agents.

The computer then shows Offline. To take it off the list, choose Remove on its card. See Manage your machines.

Delete everything

Section titled “Delete everything”

To also delete this computer’s connection and the CommandChain folders on it, add the purge option to the uninstall:

  • macOS and Linux: --uninstall --purge. This deletes the ~/.commandchain folder and the log folder.
  • Windows: -Uninstall -Purge. This deletes the %USERPROFILE%\.commandchain folder and the %LOCALAPPDATA%\CommandChain folder, which holds the logs.

If you set COMMANDCHAIN_RUNNER_STATE_DIR, the purge deletes that folder instead of .commandchain, on every system.

The .commandchain folder includes a workspaces folder. If you kept work there that you have not pushed, copy it somewhere else first: a purge deletes it.

After a purge, installing again shows a new code to approve.

Next steps

Section titled “Next steps”