CLI Reference
This page tracks the current Bosun CLI surface from bosun --help,
the task CLI, and the package bin entries shipped in the repo.
Core commands
| Command or flag |
Description |
bosun |
Start Bosun with the current config. |
bosun --setup |
Launch the web-based setup wizard. |
bosun --setup-terminal |
Run the legacy terminal setup wizard. |
bosun --doctor |
Validate the resolved Bosun environment and config. |
bosun --where |
Show the resolved Bosun config directory. |
bosun --help |
Show command help. |
bosun --version |
Print the installed version. |
Runtime and service commands
| Flag |
Description |
--daemon, -d |
Run detached with a PID file. |
--stop-daemon |
Stop a running daemon. |
--daemon-status |
Check daemon status. |
--terminate |
Hard-stop Bosun monitor and companion processes. |
--sentinel |
Start telegram-sentinel in companion mode. |
--sentinel-stop |
Stop a running sentinel. |
--sentinel-status |
Show sentinel status. |
--enable-startup |
Register Bosun to auto-start on login. |
--disable-startup |
Remove the startup service. |
--startup-status |
Check startup service status. |
bosun --daemon --sentinel
bosun --daemon-status
bosun --sentinel-status
bosun --terminate
Workspace commands
| Flag |
Description |
--workspace-list |
List configured workspaces. |
--workspace-add <name> |
Create a new workspace entry. |
--workspace-switch <id> |
Switch active workspace. |
--workspace-add-repo |
Add a repository to a workspace interactively. |
--workspace-health |
Run workspace health diagnostics. |
Task CLI
Bosun also ships a dedicated task-management CLI surface:
| Subcommand |
Description |
bosun task list |
List tasks with filters like status, priority, and tags. |
bosun task create |
Create tasks from flags, inline JSON, or bulk payloads. |
bosun task get |
Show one task in detail. |
bosun task update |
Patch task fields. |
bosun task delete |
Delete a task. |
bosun task stats |
Show aggregate task statistics. |
bosun task import |
Bulk-import tasks from JSON. |
bosun task list --status todo --json
bosun task create --title "feat(ui): add retry queue" --priority high --status todo
bosun task update <id> --status inprogress
bosun task import ./backlog.json
Operator and debugging flags
| Flag |
Description |
--tool-log <ID|list|prune> |
Retrieve, list, or prune cached tool outputs. |
--context-index [mode] |
Run the context index workflow in run, status, or search mode. |
--context-index-query <text> |
Text query for context index search. |
--context-index-limit <n> |
Max context-index results. |
--shell, --interactive |
Enable interactive shell mode in the monitor. |
--desktop, --portal |
Launch the Electron desktop portal. |
--desktop-shortcut |
Create a desktop shortcut for the portal. |
Logging and runtime tuning
| Flag |
Description |
--log-dir <path> |
Override the log directory. |
--echo-logs |
Echo raw orchestrator output to the console. |
--quiet, -q |
Show only warnings and errors. |
--verbose, -V |
Enable debug-level terminal output. |
--trace |
Show trace-level output. |
--log-level <level> |
Set an explicit log level. |
--script <path> |
Override the orchestrator script path. |
--args "<args>" |
Arguments passed to the orchestrator script. |
--restart-delay <ms> |
Delay before restart on crash (default: 180000). |
--max-restarts <n> |
Cap restarts, where 0 means unlimited. |
Companion binaries
| Binary |
Description |
bosun-task |
Direct entrypoint for task CLI operations. |
bosun-setup |
Direct setup entrypoint. |
bosun-chat-id |
Discover your Telegram chat ID. |
bosun-shared-workspaces |
Manage shared workspace registry entries. |
telegram-sentinel |
Standalone sentinel launcher. |
Legacy codex-monitor aliases are still shipped for compatibility,
but current documentation should treat bosun as the canonical CLI name.