CLI reference

Run boba --help (or boba <command> --help) for the authoritative, built-in help. This page summarizes the commands.

Sessions

`boba`

With no command, Boba starts the interactive terminal UI. On a machine with no config, it runs the setup wizard first.


boba [--profile <profile>]

-p, --profile <profile> — profile to use for the session.

`boba init`

First-run setup: detects agent CLIs on your PATH (claude, codex), walks you through a provider otherwise, and writes ~/.botbandit/botbandit.config.yaml. In background-service mode it can also connect the agent to a web app: it asks for the URL and a personal access token and checks both live.

Refuses if a config already exists, and needs an interactive terminal.

`boba run <prompt...>`

Run a single prompt and print the result.


boba run "Summarize the README." --profile coder

-s, --system <systemPrompt> — optional system prompt.
-p, --profile <profile> — profile to use.

`boba resume <sessionId>`

Reattach to an existing session.

-p, --profile <profile> — override the profile stored in the session.

`boba run-task <file>`

Run a markdown document’s body as a headless session — no TUI. The scheduler uses the same path, so this is how you test a scheduled task by hand.


boba run-task ./morning-triage.md --profile coder

-p, --profile <profile> — overrides the document’s profile.
-m, --model <model> — model override (must belong to the profile’s provider).
--json — emit raw session events as JSON lines instead of rendered text.

Daemon

`boba daemon`

Run the local session-owning daemon in the foreground. Thin clients (TUI, web, Telegram) attach to it; it otherwise starts on demand.

Subcommand	What
`boba daemon status`	Whether it’s running — pid, uptime, sessions
`boba daemon logs`	The daemon log (`-n <count>`, `-f` to follow)
`boba daemon stop`	Stop gracefully (`--force` if sessions are running)
`boba daemon restart`	Restart, starting it if not running (`--force`)

Restart after changing config or extensions.

Providers

`boba auth`

Manage provider authentication.


boba auth login openai-codex    # sign in via OAuth
boba auth status openai-codex   # stored credential status
boba auth logout openai-codex   # clear credentials

openai-codex (a ChatGPT Plus/Pro subscription) is currently the only OAuth provider; other providers use API keys from your config.

`boba subscriptions`

Show the daemon’s LLM account status — subscription windows, resets, freshness.

--refresh — poll every collector before reporting.
--json — print the raw snapshot instead of the report.

Not a command

Telegram is a resident service, not a subcommand: configure extensions.telegram.token and it runs with the daemon. See Telegram.

Extensions can add their own commands, so boba --help on your machine may list more than this page does.