Command line reference

The CommandChain app on your computer is the commandchain-runner command. Most of the time you run it with no arguments and follow what it shows. Every command in commandchain-runner --help is on this page.

Text in angle brackets is filled in by your computer.

commandchain-runner and commandchain-runner run [url]

Connect this computer to CommandChain, or check on it if it is already connected. Running commandchain-runner on its own is the same as commandchain-runner run.

It first prints the version, the computer name and the coding agents it found, then does one of these:

• Already running (in the background, in another terminal, or started with sessions-connect): prints its status and leaves it alone.
• Background app installed but not running: pairs this computer if needed, prints “Starting CommandChain in the background…” and starts it.
• No background app: pairs this computer if needed and runs in this terminal until you press Ctrl-C.

If no coding agent is installed, or none is signed in, it first walks you through setting one up before it connects the computer. See First-run setup below.

When the background app is running and connected, you see:

✔ CommandChain is running in the background and connected as <name>.
  Open CommandChain:  <link>
  Restart it:         <restart command>
  Log:                <log file>

When it is running but has not reached CommandChain recently, the first line reads instead:

! CommandChain is running in the background but has not reached <server> since <time>.

url is the CommandChain address. Leave it out to use COMMANDCHAIN_URL if you set it, else the address this computer was installed with, else the hosted CommandChain. Anything other than this computer must use HTTPS; plain http:// works only for localhost, 127.0.0.1 or [::1]. An address with a user name, password, query or fragment is refused with:

<url> is not a CommandChain address. Run commandchain-runner --help to see the commands.

Flag	What it does
--display-name <name>	Computer name shown in CommandChain. Default: <user>@<hostname>, or the name it already has.
--force-pair	Connect this computer again with a new code, replacing its saved connection.
--no-open	Do not open the browser to approve the code.
--plain	Print plain log lines instead of the friendly text.
--no-auto-update	Do not update CommandChain automatically during this run. See Automatic updates.

First-run setup

When you run commandchain-runner in a terminal and no coding agent is installed, it shows a numbered menu to install Claude Code, Codex or both. You cannot skip it: CommandChain needs an agent to do any work.

• Type the numbers to install, for example 1 2, then press Enter. Press Enter alone to install the first one.
• Each one installs as you, with the vendor’s own installer. Codex installs with npm, so it needs npm on this computer.
• To use GitHub Copilot, OpenCode or Cursor instead, install it yourself, then type r and press Enter to check again.

Then it asks you to sign in to each agent you installed, with that agent’s own sign-in: your browser, or for Codex a device code if you type d. It checks that the sign-in worked before it connects the computer. If agents are installed but none is signed in, it goes straight to signing in.

Press Ctrl+C at any prompt to quit. The background app, which runs without a terminal, never shows this setup.

commandchain-runner status

Shows whether CommandChain is running on this computer and connected, as a list: server, name, state, when it was paired, the computer id and the pairing file.

CommandChain on this computer
  server       <server>
  name         <name>
  state        connected, last check-in <n> seconds ago (background app)

Flag	What it does
--url <url>	Only show the connection to this CommandChain address.

commandchain-runner sessions-connect [url]

Connects this computer to CommandChain and runs your coding agents’ sessions with their own settings. The background app runs this command; you do not normally run it yourself. It is useful for capturing a debug log (see Get help).

url is the CommandChain address. Leave it out to use the hosted CommandChain. Unlike run, this command does not read COMMANDCHAIN_URL or the address this computer was installed with. The HTTPS and localhost rules are the same as for run.

Flag	What it does
--display-name <name>	Computer name shown in CommandChain. Default: <user>@<hostname>, or the name it already has.
--force-pair	Replace this computer’s saved connection with a new one.
--pair-only	Connect this computer, then exit without starting sessions.
--no-pair	Never ask for a new code; exit if this computer is not connected. Used by the background app.
--open	Open the browser to approve the code.
--no-claude-terminal-integration	Do not connect Claude Code sessions you start in a terminal.
--poll-interval-ms <milliseconds>	How often to check for new messages, in milliseconds. Default: 1000.
--no-auto-update	Do not update CommandChain automatically during this run.

commandchain-runner update

Checks for a new version of CommandChain and installs it. CommandChain also does this by itself; see Update or uninstall.

• commandchain-runner update: installs the latest version now, if it is newer. The background app switches to it the next time nothing is in progress.
• commandchain-runner update --check: only says whether a new version is available.
• commandchain-runner update --auto off: turns automatic updates off on this computer. --auto on turns them back on. The background app picks up the change without a restart.

CommandChain <version> is available. You have <version>. Run commandchain-runner update to install it.

commandchain-runner logout [url]

Disconnects this computer from a CommandChain server and deletes its saved connection. url defaults to the address this computer uses.

Disconnected this computer from <server>.

If the background app was running, it is stopped, so the computer goes offline in CommandChain. If there was no saved connection, it prints This computer has no saved connection to <server>. To connect again, run commandchain-runner.

commandchain-runner version

Prints the CommandChain version.

commandchain-runner machine

Diagnostics. Shows this computer’s coding agents and folders as JSON, without starting an agent.

• commandchain-runner machine inspect: prints this computer’s platform, home folder and installed coding agents as JSON.
  • --claude-path <path>: path to the Claude Code program.
  • --codex-path <path>: path to the Codex program.
• commandchain-runner machine directories <path>: lists the folders inside an absolute folder path as JSON.

commandchain-runner claude-integration

Installs and manages the connection for Claude Code sessions you start in a terminal. See Connect Claude Code in your terminal.

• commandchain-runner claude-integration install --registry <path>: installs the CommandChain plugin for Claude Code. Not available on Windows yet. Restart Claude Code afterwards.
• commandchain-runner claude-integration uninstall: removes only the CommandChain plugin from your Claude Code user settings.
• commandchain-runner claude-integration status: shows the installed Claude Code plugins.

install requires --registry <path>, the path to the private CommandChain connection file. The CommandChain app supplies it, so you do not normally run install yourself. uninstall takes the same option, but there it is optional. On Windows, install prints a message saying it is not available yet.

Installer options

The install command is the one in Install the CommandChain app. Run it again with options to change how CommandChain is installed. With no options, it installs or updates CommandChain, runs it in the background where your computer allows it, and connects this computer.

macOS and Linux (install.sh)

Options go after sh -s --. The -s tells sh to read the script from the download, and -- passes everything after it to the installer. You can combine options. For example, to install without the background app and with your own computer name:

curl -fsSL https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.sh | sh -s -- --no-service --display-name "Work laptop"

To show what is installed and whether it runs:

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

Option	What it does
--server <url>	The CommandChain server to pair with. Pass this only for your own CommandChain server.
--display-name <name>	How this computer appears in CommandChain. Default: user@host.
--version <tag>	Release to install, for example v0.14.0. Default: the latest.
--prefix <dir>	Where the program goes. Default: $HOME/.local/bin.
--service	Keep CommandChain running in the background. This is already the default whenever your login can run a background app; with this option the install stops instead when it cannot.
--no-service	Run CommandChain in this terminal only. Removes a background app installed earlier.
--status	Show what is installed and whether it runs.
--uninstall	Remove the program and the background app.
--purge	With --uninstall: also delete the pairing, CommandChain’s workspaces (including any work in them that was never pushed) and the logs. To use this computer again, you connect it with a new code.
--help	Show the installer’s help.

Windows (install.ps1)

Options need the longer form of the command, which runs the downloaded installer as a script block and passes the options after it. You can combine options. For example, to install without the background app and with your own computer name:

& ([scriptblock]::Create((irm https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.ps1))) -NoService -DisplayName "Work laptop"

To show what is installed and whether it runs:

& ([scriptblock]::Create((irm https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.ps1))) -Status

Option	What it does
-Server <url>	The CommandChain server to pair with.
-DisplayName <name>	How this computer appears in CommandChain.
-Version <tag>	Release to install. Default: the latest.
-Service	Keep CommandChain running in the background, and stop the install if this computer does not allow it.
-NoService	Run CommandChain in this window only. Removes a background app installed earlier.
-Status	Show what is installed and whether it runs.
-Uninstall	Remove the program and the background app.
-Purge	With -Uninstall: also delete the pairing, your session history and the logs. To use this computer again, you connect it with a new code.
-PrintVersion	Print the installer’s version and exit.
-FromSettings	Used by the uninstall entry in Windows Settings: keeps the window open until you press Enter. You do not need it.

Next steps

• Environment variables
• Keep the CommandChain app running