Skip to content
CommandChain CommandChain CommandChain Docs

Upgrades and uninstall

Everything on this page is the same script you installed with. Keep it, or fetch it again from the release URL; both work.

Terminal window
sh install.sh --server https://your-commandchain   # upgrade, keeping the pairing
sh install.sh --status                             # what is installed, and is it running
sh install.sh --uninstall                          # stop and remove the service and the program
sh install.sh --uninstall --purge                  # also delete credentials and workspaces

Upgrading

Section titled “Upgrading”

Re-running the installer is the upgrade. There is no separate command. It downloads the new release, verifies its checksum, replaces the program atomically, rewrites the service definition, and restarts the service.

Two things it deliberately does not do:

  • It does not re-pair. It finds the saved credential and keeps it, so the runner stays the same machine in your fleet with the same history. The output says Already paired.
  • It does not leave you on a broken version. If the new release cannot stay up after the restart, the installer rolls back to the one that could.

Pin a version with --version when you need to:

Terminal window
sh install.sh --server https://your-commandchain --version v1.2.0

Checking what is installed

Section titled “Checking what is installed”

--status reads local state only. It needs no network and no running workspace:

Terminal window
$ sh install.sh --status


CommandChain runner


  program    /home/maya/.local/bin/commandchain-runner (0.1.2)
  service    /home/maya/.config/systemd/user/commandchain-runner.service
  state      running
  logs       /home/maya/.local/state/commandchain-runner/runner.log
  workspaces /home/maya/.commandchain/workspaces
  state dir  /home/maya/.commandchain


  follow the log:  journalctl --user -u commandchain-runner -f   (or: tail -f /home/maya/.local/state/commandchain-runner/runner.log)


Credentials file: /home/maya/.commandchain/runner.json


  https://your-commandchain
    tenant       alpenglow
    runnerId     32c152e4-3d5e-49a1-b3df-20b95c0a74b6
    displayName  maya-macbook
    adapters     claude-code-cli
    pairedAt     2026-07-23T20:32:15.947Z

Read it top down: the program and its version, whether the service is actually running, where to follow the log, and which instances this machine is paired with. The credential itself is not printed, here or anywhere.

On macOS the log line names tail instead of journalctl, because the service is a launch agent rather than a systemd unit.

Uninstalling

Section titled “Uninstalling”

--uninstall is the careful one. It stops and removes the service and deletes the program, and it keeps your pairing credential and your workspaces.

Terminal window
$ sh install.sh --uninstall

That is deliberate. A task branch that has not been pushed yet lives in a workspace, and a preserved pairing means reinstalling later puts the same machine back in your fleet rather than a new one.

--purge is the thorough one, and it only ever happens on that explicit second flag:

Terminal window
$ sh install.sh --uninstall --purge

It additionally deletes ~/.commandchain: the pairing credential, the captured coding-agent setup directory, and every workspace, including work that has not been pushed.

None of these commands asks for administrator rights, and none of them touches anything outside your home directory.

Removing the runner from your workspace

Section titled “Removing the runner from your workspace”

Uninstalling from the machine stops the runner; it does not remove the record of it. To retire it in the app, open Settings, then Runners, and remove it there. A runner has to be offline and holding no active work before it can be retired, which is what stops a machine’s history being orphaned mid-run.

Next steps

Section titled “Next steps”