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 when an AI agent host is the caller. Reach for the REST API when you’re building your own pipeline in code.

Install

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:

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.

Getting Started

Headless

Business Packs

Trust Intelligence

Governance

Daily Report

API Reference

Self-Hosting

Integrations

Agent Deployer

CLI

CLI

Install

Commands

Core lifecycle

Workspace

Work & chat

Directives & approvals

Guardian

Provider management

Key flags

`bossmode init`

`bossmode reset`

Second device

Guardian kill switch

Config

Environment variables

CI usage

Troubleshooting

​CLI

​Install

​Commands

​Core lifecycle

​Workspace

​Work & chat

​Directives & approvals

​Guardian

​Provider management

​Key flags

​bossmode init

​bossmode reset

​Second device

​Guardian kill switch

​Config

​Environment variables

​CI usage

​Troubleshooting

CLI

Install

Commands

Core lifecycle

Workspace

Work & chat

Directives & approvals

Guardian

Provider management

Key flags

`bossmode init`

`bossmode reset`

Second device

Guardian kill switch

Config

Environment variables

CI usage

Troubleshooting