CLI Reference
The authoritative reference for every command, subcommand, and flag is the help text built into the binary:
boss --help
boss <subcommand> --help
Top-level commands
boss
The interactive terminal UI and the CLI for non-interactive operations.
boss # launch the Terminal UI (TUI) on the Home screen
boss settings # view or update global settings
boss repo ls # list configured repos
boss repo update <repo-id> ... # change repo fields from the shell
boss repair doctor # health-check the auto-repair pipeline
boss mcp
Manage the local MCP server that exposes Bossanova to AI agents.
| Subcommand | Description |
|---|---|
boss mcp install | Install and start the local MCP service (--port, --force) |
boss mcp status | Show whether the service is installed / running |
boss mcp start | Start or restart the installed service |
boss mcp stop | Stop the service, leaving the service file in place |
boss mcp uninstall | Stop and remove the service file |
See the MCP guide for agent wiring and the tool catalog.
boss new and boss chat (scripted chat control)
Create a session non-interactively and drive its chat from the shell (or, with the same reach, from an MCP agent):
boss new --repo <r> --prompt <p> --detach # create a session, print session-id + chat-id, exit
boss new runs non-interactively when both --repo and --prompt are given (--detach
is then implicit; --no-attach is an alias). --agent <a> overrides the default agent
plugin; --title <t> is optional (auto-derived from the prompt when absent).
| Subcommand | Description |
|---|---|
boss chat send <session-id|chat-id> <msg> | Deliver a follow-up message to a running chat; wakes a sleeping chat |
boss chat show <session-id|chat-id> | Print the transcript (--result-only for just the final result, --limit N to cap messages) |
boss chat wait <session-id|chat-id> | Block until the chat is idle / waiting, then print the final result (--timeout 30m) |
A <session-id> targets that session's primary chat; a <chat-id> (the
agent_session_id printed by boss new --detach) targets a specific chat.
bossd
The background daemon. Normally started by Homebrew's launchd plist or
your equivalent service manager. You rarely run it by hand. It takes
configuration from environment variables and settings.json; there
are no subcommands.
bossd # run in foreground
bossd --version # print version info
Settings overrides
Most settings can be overridden by environment variable. Precedence
(highest wins): environment variable → settings.json → hardcoded
default. See
Settings → Environment overrides
for the table.
A hand-curated reference page is on the roadmap. If you hit something ambiguous in the help text, open an issue at bossanova-dev/bossanova/issues.