CLI 参考

bub 提供六个公开命令组：run、gateway、chat、install、update 和 login。另外保留了一个隐藏的诊断命令：hooks。

bub run

将一条入站消息通过完整框架 pipeline 并打印出站结果。

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

常用选项：

• --workspace/-w：工作区根目录，在顶层 CLI 声明一次，所有子命令共享
• --channel：来源 channel（默认 cli）
• --chat-id：来源端点 id（默认 local）
• --sender-id：发送者身份（默认 human）
• --session-id：显式 session id（默认为 <channel>:<chat_id>）

以逗号为前缀的输入进入内部命令模式：

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

未知的逗号命令会回退到 shell 执行：

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

bub hooks

打印启动时发现的 hook 到插件的绑定关系。

uv run bub hooks

hooks 仍可用于诊断，但在顶层帮助中被隐藏。

bub gateway

启动 channel 监听模式（默认启用所有非 cli channel）。

uv run bub gateway

仅启用指定 channel：

uv run bub gateway --enable-channel telegram

bub chat

通过 cli channel 启动交互式 REPL 会话。

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

chat 复用顶层的 --workspace/-w 选项。默认设置 chat_id=local，channel 保持为 cli，底层 CLI channel 的 session id 保持 cli_session，除非你传入 --session-id。

bub install

将包安装到 Bub 管理的插件项目中；如果未指定包名，则同步该项目。

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

选项与行为：

• --project：用于 Bub 管理插件的 uv 项目路径
• BUB_PROJECT：等效于 --project 的环境变量
• 默认项目路径：~/.bub/bub-project
• 如果项目尚不存在，Bub 会自动创建一个空的 uv app 项目
• 在运行 install 或 update 之前，Bub 必须安装在虚拟环境中

支持的包指定格式：

• https://... 或 git@...：作为 Git 依赖安装
• owner/repo 或 owner/repo@ref：展开为 GitHub 仓库 URL
• name：作为普通包依赖传入
• name@ref：从 bub-contrib 的 packages/<name> 解析指定的 Git ref

如果未提供包名，install 会执行项目同步而非添加新依赖。

bub update

更新 Bub 管理的插件项目中的依赖。

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

行为：

• 不指定包名时，升级整个项目
• 指定包名时，仅升级选中的依赖
• 使用与 install 相同的 --project / BUB_PROJECT 路径
• 如果管理项目尚不存在，先创建它

bub login

通过 OpenAI Codex OAuth 认证，并将凭据持久化到 CODEX_HOME（默认 ~/.codex）。

uv run bub login openai

当本地重定向服务器不可用时，可使用手动回调模式：

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

登录后，无需设置 BUB_API_KEY 即可使用 OpenAI 模型：

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

如果上游端点要求特定的请求载荷格式，请设置 BUB_API_FORMAT：

• completion：传统 completion 风格格式；默认值
• responses：OpenAI Responses API 格式
• messages：Anthropic Messages API 格式

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

备注

• --workspace 在子命令之前解析，例如 uv run bub --workspace /repo chat。
• install 和 update 操作的是 Bub 管理的插件项目，而非当前工作区。
• uninstall() 存在于内置模块中，但目前未作为公开 CLI 命令暴露。
• run 按如下格式打印每条出站消息：

[channel:chat_id]
content