Skip to main content

​
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

CommandDescription
bossmode (no args)Open the local operator TUI
bossmode helloConfirm the CLI can read local pairing and workspace state
bossmode initInitialize the local BossMode brain, start the local GUI, and open it in your browser
bossmode startStart the detached local BossMode GUI server
bossmode stopStop the running local BossMode server
bossmode statusShow the current local daemon, tier, sync, and SQLite status
bossmode doctorCheck the health of the local BossMode install
bossmode updateCheck npm for a newer CLI, run local migrations, and restart the daemon if needed
bossmode resetStop the daemon and clear state. Use --full to wipe ~/.bossmode/ entirely
bossmode reregisterRegister device signing key (upgrade path for pre-Apr-17 installs)
bossmode tuiOpen the local operator TUI

​
Workspace

CommandDescription
bossmode workspace listFetch 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

CommandDescription
bossmode workloopPoll 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

CommandDescription
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 packetsList local operator work packets
bossmode report [window]Read the local operator report for today or this week

​
Guardian

CommandDescription
bossmode killQueue a Guardian kill-switch approval

​
Provider management

CommandDescription
bossmode provider add <provider>Connect an AI provider using an API key or OAuth flow
bossmode provider listList 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

FlagDescription
--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
--wizardRun 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-existingRegister 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

FlagDescription
--fullWipe ~/.bossmode/ entirely — removes brain DB, config, and all provider keys
--softStop daemon and clear pending directives only (default)
--yesSkip 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

VariableDescription
BOSSMODE_API_URLOverride the API base URL (defaults to https://bossmode.ing)
BOSSMODE_CONFIG_DIROverride ~/.bossmode/ on disk
BOSSMODE_DAEMON_PORTPort for the local daemon (defaults to 5173)
BOSSMODE_LOG_LEVELdebug, 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.