> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bossmode.ing/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The bossmode CLI — install, pair devices, manage workspaces, approve directives, and run the local workloop from any terminal or CI environment.

# CLI

`@bossmode/cli` is the terminal-native surface for BossMode. Runs on macOS, Linux, and Windows (via WSL). Spawns your existing vendor CLI (Claude, Codex, Hermes, OpenClaw) under its own OAuth — we never hold your vendor tokens.

Reach for the CLI when you want to drive BossMode from a shell, a CI runner, or a remote SSH session. Reach for [MCP](/headless/mcp) when an AI agent host is the caller. Reach for the [REST API](/headless/api) when you're building your own pipeline in code.

## Install

```bash theme={null}
npx @bossmode/cli@latest init --wizard
```

The `--wizard` flag runs the minimal terminal onboarding: creates or connects your workspace, mints a device signing key, and starts the local daemon. Add `--install-token <token>` when automating from a CI seed step.

## Commands

The following commands are sourced from `packages/bossmode-cli/src/cli.ts`.

### Core lifecycle

| Command                | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `bossmode` *(no args)* | Open the local operator TUI                                                           |
| `bossmode hello`       | Confirm the CLI can read local pairing and workspace state                            |
| `bossmode init`        | Initialize the local BossMode brain, start the local GUI, and open it in your browser |
| `bossmode start`       | Start the detached local BossMode GUI server                                          |
| `bossmode stop`        | Stop the running local BossMode server                                                |
| `bossmode status`      | Show the current local daemon, tier, sync, and SQLite status                          |
| `bossmode doctor`      | Check the health of the local BossMode install                                        |
| `bossmode update`      | Check npm for a newer CLI, run local migrations, and restart the daemon if needed     |
| `bossmode reset`       | Stop the daemon and clear state. Use `--full` to wipe `~/.bossmode/` entirely         |
| `bossmode reregister`  | Register device signing key (upgrade path for pre-Apr-17 installs)                    |
| `bossmode tui`         | Open the local operator TUI                                                           |

### Workspace

| Command                                 | Description                                                     |
| --------------------------------------- | --------------------------------------------------------------- |
| `bossmode workspace list`               | Fetch the server-authorized workspace list for this device      |
| `bossmode workspace switch <workspace>` | Switch local config to a server-authorized workspace slug or id |

### Work & chat

| Command                | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `bossmode workloop`    | Poll BossMode for CLI-heartbeat work packets, execute them locally, and post receipts |
| `bossmode chat [text]` | Talk to the local BossMode consigliere over the daemon SSE chat stream                |

### Directives & approvals

| Command                         | Description                                           |
| ------------------------------- | ----------------------------------------------------- |
| `bossmode directive <text>`     | Submit a boss directive into the local approval queue |
| `bossmode approve <approvalId>` | Approve and execute a pending local operator approval |
| `bossmode reject <approvalId>`  | Reject a pending local operator approval              |
| `bossmode packets`              | List local operator work packets                      |
| `bossmode report [window]`      | Read the local operator report for today or this week |

### Guardian

| Command         | Description                           |
| --------------- | ------------------------------------- |
| `bossmode kill` | Queue a Guardian kill-switch approval |

### Provider management

| Command                               | Description                                           |
| ------------------------------------- | ----------------------------------------------------- |
| `bossmode provider add <provider>`    | Connect an AI provider using an API key or OAuth flow |
| `bossmode provider list`              | List all configured AI provider connections           |
| `bossmode provider health <provider>` | Check the health of a provider connection             |
| `bossmode provider remove <provider>` | Disconnect and remove credentials for an AI provider  |

## Key flags

### `bossmode init`

| Flag                             | Description                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------- |
| `--token <token>`                | Existing Pro token from bossmode.ing                                            |
| `--install-token <installToken>` | One-time install token from web onboarding (non-interactive)                    |
| `--email <email>`                | Email for instant verification                                                  |
| `--name <name>`                  | Name for instant verification                                                   |
| `--wizard`                       | Run the minimal Wave 9 onboarding wizard in the terminal                        |
| `--family-runtime <runtime>`     | Spawn the local family in this runtime (`claude_code`, `openclaw`, or `hermes`) |
| `--consigliere-existing`         | Register an existing local agent session as the consigliere                     |
| `--api-url <url>`                | Override the BossMode API URL                                                   |
| `--plan <plan>`                  | Plan tier (`open`, `operator`, `studio`, `scale`) — persisted to local config   |

### `bossmode reset`

| Flag     | Description                                                                    |
| -------- | ------------------------------------------------------------------------------ |
| `--full` | Wipe `~/.bossmode/` entirely — removes brain DB, config, and all provider keys |
| `--soft` | Stop daemon and clear pending directives only (default)                        |
| `--yes`  | Skip confirmation prompt                                                       |

## Second device

Install the CLI on a second machine the same way. Both devices pair to the same workspace. Directives flow both ways via the cross-device sync substrate.

## Guardian kill switch

`bossmode kill` requires triple-confirm (`KKK` on the TUI). Pauses every agent in the family immediately. `bossmode guardian restore` re-enables after operator approval.

## Config

`~/.bossmode/config.json` holds:

* Device ID and signing key
* Workspace binding
* Daemon port + log path

Never commit this file to git.

## Environment variables

| Variable               | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `BOSSMODE_API_URL`     | Override the API base URL (defaults to `https://bossmode.ing`) |
| `BOSSMODE_CONFIG_DIR`  | Override `~/.bossmode/` on disk                                |
| `BOSSMODE_DAEMON_PORT` | Port for the local daemon (defaults to 5173)                   |
| `BOSSMODE_LOG_LEVEL`   | `debug`, `info`, `warn`, `error`                               |

## CI usage

For non-interactive contexts (CI, automation) pair via the install token path:

```bash theme={null}
BOSSMODE_API_TOKEN=cp_live_... \
  npx @bossmode/cli@latest init \
  --install-token "$BOSSMODE_INSTALL_TOKEN" \
  --yes
bossmode directive "build the weekly brief" --yes
```

All commands that would normally prompt accept `--yes` to auto-confirm.

## Troubleshooting

* **`Cannot prompt for input`** — you're in a non-TTY shell. Pass `--yes` flags or set env vars instead.
* **`DEVICE_REVOKED`** — workspace admin revoked this device. Run `init --wizard` again to re-pair.
* **`daemon already running`** — `bossmode stop` then `bossmode start`.