CLI Reference

The cihub CLI manages your Companion Hub stack, apps, models, and cloud registration from the terminal. It is the same tool bundled with the desktop app and available as an npm package.

Install

npm install -g ci-hub
cihub --help

One-off without installing:

npx --package ci-hub cihub --help

Homebrew, Scoop, and other package managers also expose cihub on PATH when you install Companion Hub.

Environments

Most commands accept an optional environment argument:

Use these meanings consistently:

• local = source-based local development
• dev = dev appliance environment using .env.dev
• staging = staging appliance environment
• prod = production appliance environment

cihub up local
cihub up dev --detached
cihub status prod

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
cihub wizard staging

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 Companion Portal 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).

Appliance-style startup

For a packaged or server-style deployment:

cihub up prod --detached
cihub up dev --detached

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]

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