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 using any desktop path:

• Download  or GitHub Releases 
• macOS: brew install --cask companion-hub (after tapping homebrew-tap )
• Windows: scoop install companion-hub (after adding the scoop bucket )
• Linux: .deb or .rpm from GitHub Releases

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

Open a new terminal after first launch, then verify:

cihub --help

On a Linux headless server where you never opened the GUI, use the bundled path directly or run companion-hub --detached first:

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

Environments

Most commands accept an optional environment argument. On a packaged install (desktop app or Linux package), commands always target your prod data directory regardless of the env name you pass.

# 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. On first run (no env file found), enters FTUE mode: checks Docker, runs setup and registration, then starts the Hub.

cihub wizard

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.

cihub register [env]

Prints your device ID and the hub.ci.computer registration URL. Open the URL in a browser to pair the device.

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]           # reset runtime state, then start again
cihub status [env]             # containers, tunnel URL, Tailscale IP, models
cihub logs [env] [service]     # stream compose logs
cihub config [env]             # resolved config values

• --detached runs the stack in the background (equivalent to docker compose up -d).
• status shows Containers (color-coded), Network (local URL, Cloudflare tunnel, Tailscale VPN IP), and Models (installed Ollama models).

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

Requires Ollama reachable on the host. See AI & 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>

Public Web

Diagnose and repair Cloudflare Gateway routing for exposable apps:

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

MCP

Enable the Hub MCP server for agent apps:

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

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> [--scopes mcp] [--capability read|write|full]
cihub api-key list

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.

Maintenance

cihub doctor [env]         # validate Docker, env files, bind mounts, and compose inputs
cihub clean [env] [--yes]  # remove generated host-state files for one environment
cihub reset [env] [--yes]  # remove runtime state for one environment
cihub uninstall [--yes]    # full machine cleanup of Hub state

• reset is the environment-scoped wipe path.
• uninstall is the machine-wide uninstall-style wipe path, including Hub data, tunnel state, containers, volumes, and related runtime files.

Help

cihub --help
cihub man
cihub version