CLI Reference

bub exposes six public command groups: run, gateway, chat, install, update, and login. It also keeps one hidden diagnostic command: hooks.

`bub run`

Run one inbound message through the full framework pipeline and print outbounds.

uv run bub run "hello" --channel cli --chat-id local

Common options:

--workspace/-w: workspace root, declared once on the top-level CLI and shared by all subcommands
--channel: source channel (default cli)
--chat-id: source endpoint id (default local)
--sender-id: sender identity (default human)
--session-id: explicit session id (default is <channel>:<chat_id>)

Comma-prefixed input enters internal command mode:

uv run bub run ",help"
uv run bub run ",skill name=my-skill"
uv run bub run ",fs.read path=README.md"

Unknown comma commands fall back to shell execution:

uv run bub run ",echo hello-from-shell"

`bub hooks`

Print hook-to-plugin bindings discovered at startup.

uv run bub hooks

hooks remains available for diagnostics, but it is hidden from the top-level help.

`bub gateway`

Start channel listener mode (defaults to all non-cli channels).

uv run bub gateway

Enable only selected channels:

uv run bub gateway --enable-channel telegram

`bub chat`

Start an interactive REPL session via the cli channel.

uv run bub chat
uv run bub chat --chat-id local --session-id cli:local

chat reuses the top-level --workspace/-w option. By default it sets chat_id=local, keeps the channel as cli, and leaves the underlying CLI channel session id at cli_session unless you pass --session-id.

`bub install`

Install packages into Bub’s managed plugin project, or sync that project if no package spec is given.

uv run bub install
uv run bub install my-plugin
uv run bub install example-owner/example-bub-plugin@main
uv run bub install https://github.com/example/bub-plugin.git

Options and behavior:

--project: path to the uv project used for Bub-managed plugins
BUB_PROJECT: environment variable equivalent of --project
default project path: ~/.bub/bub-project
if the project does not exist yet, Bub creates a bare uv app project automatically
Bub must be installed inside a virtual environment before install or update can run

Accepted spec forms:

https://... or git@...: installed as a Git requirement
owner/repo or owner/repo@ref: expanded to a GitHub repository URL
name: passed through as a normal package requirement
name@ref: resolved from bub-contrib as packages/<name> at the given Git ref

If no package specs are provided, install runs a project sync instead of adding anything new.

`bub update`

Update dependencies inside Bub’s managed plugin project.

uv run bub update
uv run bub update my-plugin another-plugin

Behavior:

with no package names, upgrades the whole project
with package names, upgrades only the selected dependencies
uses the same --project / BUB_PROJECT location as install
creates the managed project first if it does not exist yet

`bub login`

Authenticate with OpenAI Codex OAuth and persist the resulting credentials under CODEX_HOME (default ~/.codex).

uv run bub login openai

Manual callback mode is useful when the local redirect server is unavailable:

uv run bub login openai --manual --no-browser

After login, you can use an OpenAI model without setting BUB_API_KEY:

BUB_MODEL=openai:gpt-5-codex uv run bub chat

If the upstream endpoint expects a specific request payload format, set BUB_API_FORMAT:

completion: legacy completion-style format; default
responses: OpenAI Responses API format
messages: Anthropic Messages API format

BUB_MODEL=openai:gpt-5-codex BUB_API_FORMAT=responses uv run bub chat

Notes

--workspace is parsed before the subcommand, for example uv run bub --workspace /repo chat.
install and update operate on Bub’s managed plugin project, not on the current workspace.
uninstall() exists in the builtin module but is not currently exposed as a public CLI command.
run prints each outbound as:

[channel:chat_id]
content