CLI reference

The cihub CLI manages your Companion Hub stack, apps, models, and CI Account registration from the terminal. It is bundled with the desktop app and Linux packages — there is no separate npm package.

Install

Install Companion Hub from ci.computer/download  — see Installation. The cihub CLI comes with the desktop app and the Linux packages.

On first launch of the desktop app, cihub is copied to:

Open a new terminal after first launch, then verify:

cihub --help

The .deb package also links cihub to /usr/bin/cihub when you install it, so on a Linux headless server where you never opened the GUI it already works. If cihub isn’t found, use the bundled path directly:

/usr/lib/companion-hub/resources/cihub --help

Quick reference

Every command group on this page, in one table. Details and flags follow in the sections below.

Environments

Most commands accept an optional environment argument. On a packaged install (desktop app or Linux package), up, down, reset, and clean always target your prod data directory regardless of the env name you pass, and cihub up runs detached unless you add --attached.

# From a git clone (contributors):
cihub up local
cihub up dev --detached
cihub status prod
 
# From a packaged install (any directory):
cihub up --detached
cihub status

Setup & registration

cihub wizard [env]

Guided setup wizard. It needs an interactive terminal. On first run (no env file found), it enters FTUE mode: it asks for an environment, checks Docker, runs setup, starts the Hub, and asks for a pairing code, then offers to install a first model.

cihub wizard

On a packaged install the environment prompt has no effect — Hub always targets the prod install — so press Enter at it. Returning users get an action menu: setup, up, register, config, MCP, down, app-list, reset, restart.

cihub setup [env]

Initializes Traefik and Docker auth config for the target environment. On a packaged install with no data folder yet, it creates one, and asks you to choose a database password unless POSTGRES_PASSWORD is set.

cihub register [env]

Pairs this Hub with your CI Account. The Hub must be running. It prints your device ID and the hub.ci.computer registration URL, then asks for the six-character pairing code you generate in your CI Account.

cihub register --code ABC123

cihub claim [env] [--email <addr>]

Creates the Hub’s first admin without a browser. Run it on the Hub, after cihub register. It’s safe to re-run: a Hub that already has an admin is reported and the command exits 0. Then sign in through your CI Account with the same email address.

cihub claim --email you@example.com

cihub device-id [--from-hub]

Prints this machine’s stable device ID. --from-hub asks the running Hub instead of resolving it locally.

Hub lifecycle

cihub up [env] [--detached]   # start the hub stack
cihub down [env]               # stop the hub stack
cihub restart [env]            # restart the target environment
cihub recreate [env] [--yes]   # reset runtime state, then start again (destructive)
cihub status [env]             # containers and ports, tunnel state, Tailscale IP
cihub logs [env] [service]     # stream compose logs
cihub config [env]             # resolved config values (env file in the current folder)

• --detached runs the stack in the background (equivalent to docker compose up -d). On a packaged install cihub up is already detached by default; add --attached to stay in the foreground. cihub restart and cihub recreate run in the foreground until you add --detached.
• Before it starts the stack, cihub up prints the Docker Compose and Docker Engine versions it found. Docker Compose older than 2.33 stops the start with a red Docker update needed box and exit code 1. Docker Engine older than 28 prints a yellow Docker Engine update recommended box, and the start continues. restart and recreate run the same check; cihub up local doesn’t.
• cihub up on a machine that has never run Hub asks you to choose a database password and creates the data folder. Set POSTGRES_PASSWORD (or CIHUB_POSTGRES_PASSWORD) to skip the prompt.
• status shows Containers (color-coded, with their published ports), Network (a dashboard line, the Cloudflare tunnel state, and the Tailscale VPN IP), and, only when Ollama runs as a container in the Hub’s Compose project, Models (installed Ollama models). Read the dashboard port from the ci-hub container row, which shows <host port>->5002/tcp: the Dashboard line prints 5002 unless your env file sets FRONTEND_PORT or BACKEND_PORT, and the Cloudflare line reads active or not configured.

Updates

cihub update [--check]                    # report CLI and stack versions, then update
cihub self-update [--to <version>] [--check]  # replace a standalone cihub binary
cihub version [--short]                   # this CLI's version, then the running Hub's build

cihub update prints the CLI version next to the running stack’s version first, then hands the update to companion-hub update. That works when companion-hub is on your PATH, which a Linux package install does. On macOS and Windows only cihub is on your PATH, so cihub update reports that there is no desktop app here: update the app from Settings → System instead. cihub self-update only applies to a standalone cihub binary; it refuses when cihub came inside the desktop package or from a source checkout. See Updating Companion Hub.

Packaged / headless startup

companion-hub --detached   # Linux headless, no GUI
cihub up --detached        # same prod install, from any shell

For source-based local development:

cihub up local

Models

cihub models list
cihub models install llama3.2
cihub models rm llama3.2

These commands run the ollama command inside an Ollama container that belongs to the Hub’s Compose project. A standard Hub install doesn’t run one, because Hub uses the Ollama on your host. On such an install every cihub models command reports Ollama container not running and exits with code 1. Manage models with ollama list, ollama pull, and ollama rm on the host instead, or pick them in Settings → AI. See AI and inference.

App lifecycle

Manage Docker containers on the host, independently of the Hub compose stack:

cihub app list
cihub app status [name]
cihub app logs <name> [--tail N]
cihub app inspect <name>
cihub app add <name> <image> [--port h:c] [--env K=V]
cihub app edit <name> <image> [--port h:c] [--env K=V]
cihub app start <name>
cihub app stop <name>
cihub app restart <name>
cihub app delete <name>
cihub app stop-managed     # stop every Hub-managed app container
cihub app remove-managed   # remove every Hub-managed app container

Those commands drive Docker directly. To run one action over every app through the running Hub, so each app goes through the same steps as the dashboard’s Batch actions menu, use:

cihub app start-all [env]      # start every stopped app
cihub app stop-all [env]       # stop every running app
cihub app restart-all [env]    # restart every running app
cihub app update-all [env]     # update every app with a newer version, with a backup of each first

Run these on the Hub machine: they need the Hub running and the device key that Hub keeps in state/settings.json. They report that the Hub accepted the request, not that the apps finished; run cihub app status to watch them change state.

Public Web

Diagnose and repair the routing for apps whose Exposure mode is Public Web:

cihub public-web status [env]
cihub public-web repair [env] [--app <name>]

These commands run only from a CI-Hub source checkout. On an installed Hub they stop with Run from a CI-Hub checkout. On an installed Hub, check the tunnel with cihub status and the Cloudflare Tunnel card in Settings → Network, and select Repair routing in the app’s settings to fix an app’s public route.

MCP

Hub’s MCP server for agent apps is on by default: Hub loads it unless MCP_ENABLED is false. These commands set or print that variable:

cihub mcp setup [env]
cihub mcp shutdown [env]
cihub mcp config [env]

They read and write the env file in the current folder (.env.local by default), so use them from a source checkout. On an installed Hub they don’t read or change the Hub’s own env file, and cihub mcp setup creates a .env.local in the folder you run it from. You don’t need cihub mcp setup before creating an API key.

Connect an agent

Wire an agent installed on this host to Companion Memory, so it gets passive capture rather than memory tools it has to call:

cihub connect openclaw --memory-url <url> --memory-key <key>
cihub connect hermes   --memory-url <url> --memory-key <key>

It probes every server you give it before touching disk, so a failed probe leaves the machine exactly as it was. The memory probe checks the key, not just the address — it calls an endpoint requiring the memory scope, so a key that would fail silently at capture time is refused up front. For openclaw it backs up the agent’s config before editing and restores it on a failed write; for hermes it stages the plugin, writes mcp_servers.hub when you pass the Hub flags, and hands the memory credentials to hermes memory setup, which you still run to finish. It configures the host it runs on — for an agent on another machine, follow the per-agent instructions in Connect an existing agent.

API keys

Mint and list the keys an MCP client uses to reach the Hub. Run these on the appliance host:

cihub api-key create --name <label> [--scope mcp|qa:read|inference] [--capability read|write|full]
cihub api-key list

mcp opens the MCP endpoint. qa:read is a read-only key for a test harness or monitor, and inference opens the OpenAI-compatible inference routes for an editor or SDK. Each of the last two must be the only scope on its key and is stored as read, so --capability write and full are refused for them.

The key is printed once, at creation, and cannot be retrieved afterwards. api-key list shows IDs, names, scopes, capability and a prefix — never the key itself.

There is no subcommand for changing an existing key — create and list are the whole CLI surface. Change a key’s capability from Settings → Security in the Hub dashboard instead.

Other command groups

• cihub login [--device] [--org <slug>], cihub logout, and cihub submit [--dry-run] <dir> sign in to Portal and submit an app folder to the marketplace. See Submit with the CLI.
• cihub pool ... operates Hub Pool from the terminal — status, a read-only doctor preflight, pairing, and routing across several Hubs. Its subcommands are listed in the Hub Pool command reference; cihub --help has a Hub Pool group, and cihub pool --help is not supported.
• cihub fleet ... installs and updates Hubs on other machines over SSH. Run cihub --help for the full list.

Maintenance

cihub doctor [env] [--repair-networks]  # validate Docker, env files, bind mounts, registration, and compose inputs
cihub clean [env] [--yes]               # remove generated host-state files for one environment
cihub reset [env] [--yes] [--dry-run]   # remove runtime state for one environment
cihub uninstall [--yes]                 # full cleanup of Hub state (source checkout only)

• doctor starts with a box that names the Hub it checks: Targeting prod install with the data folder on an installed Hub, or Targeting checkout with the checkout path. In a checkout the box turns yellow when the running Hub was started from another folder, and says where to run cihub doctor to check that Hub. It also compares the CLI and stack versions: a cihub run from a source checkout names no release, so doctor compares commits and a difference is only a note. And it fails a registered Hub that has no admin yet (run cihub claim). It probes the Hub’s own API port, Ollama, vLLM, and Lemonade, plus an MTPLX or speculative-inference server only when its URL is in the env file, and leaves off any service that isn’t listening on the host.
• reset is the wipe path for an installed Hub. It removes your installed apps, the Hub containers and volumes, the data folder, and the Hub’s tunnel token and registration files. --dry-run lists what would go without deleting it, and --yes skips the confirmation prompt. On an installed Hub, cihub reset --yes is how you remove the Hub’s data from the terminal. See Uninstalling.
• uninstall is the machine-wide wipe path for a source checkout. It needs to run from a CI-Hub repository directory, so on an installed Hub it stops with Run from a CI-Hub checkout and exits with code 2. Use reset there.

Help

cihub --help
cihub man
cihub version