CLI

bub 由应用层提供，需要安装 app 可选依赖。本页只列内置命令；插件可以通过 register_cli_commands 增加命令。

全局选项

bub [OPTIONS] COMMAND [ARGS]...

选项	类型	默认值	说明
--workspace, -w	路径	当前工作目录	设置工具工作目录、技能发现和相对路径解析的基准
--version, -V	开关	—	显示 Bub 版本并退出
--help	开关	—	显示帮助

--workspace 不改变 BUB_HOME 或配置文件位置。

不带命令时执行 BubFramework.default_command，内置默认值为 chat。缺少 app 依赖时，进程打印缺失包和安装命令后以退出码 1 结束。

bub run

处理一条消息的完整 Turn，并将 TurnResult.outbounds 打印到 stdout；不启动渠道管理器。

bub run [OPTIONS] MESSAGE

参数与选项	类型	默认值	说明
MESSAGE	文本	必填	消息正文；以命令前缀开头时执行命令
--channel	文本	cli	入站渠道名
--chat-id	文本	local	入站聊天 ID
--sender-id	文本	human	写入 context.sender_id
--session-id	文本	<channel>:<chat-id>	覆盖会话 ID

输出格式：

[channel:chat_id]
<正文>

• 不启动 mcp.lifecycle、acp-server 等渠道或后台服务。
• 不自动发送回复到聊天平台。
• 仍执行 provide_tape_store、provide_lifespan 和 provide_steering_inbox 的资源作用域。
• 模型阶段使用非流式 HookRuntime.run_model。

bub chat

启动交互式 REPL，启用 cli 渠道并附加已启用的 Lifecycle 渠道。

bub chat [OPTIONS] [INITIAL_PROMPT]

参数与选项	类型	默认值	说明
INITIAL_PROMPT	文本	—	REPL 启动后立即提交
--chat-id	文本	local	CLI 聊天 ID
--session-id	文本	cli_session	会话 ID

chat 强制流式输出并忽略 BUB_STREAM_OUTPUT。没有 cli 渠道时以退出码 1 结束。

REPL 命令前缀由 BUB_COMMAND_PREFIX 决定，默认为 ,；,help 列出当前命令。

bub gateway

启动渠道管理器并常驻运行已启用的渠道。

bub gateway [OPTIONS]

选项	类型	默认值	说明
--enable-channel	文本，可重复	读取 BUB_ENABLED_CHANNELS	限定或排除渠道
--install	开关	关闭	安装并启动当前用户的后台服务
--uninstall	开关	关闭	停止并卸载后台服务

--install 与 --uninstall 互斥。命令行渠道选择优先于 BUB_ENABLED_CHANNELS。

渠道选择

BUB_ENABLED_CHANNELS 使用逗号分隔；--enable-channel 可以重复。

enabled_channels	结果
all	所有 enabled 且不属于 Interface 的渠道，减去 !name
显式普通渠道	列表中 enabled 且未被排除的渠道
显式普通渠道 + Lifecycle	先选择普通渠道，再附加所有已启用的 Lifecycle
只有 Lifecycle	只启动这些 Lifecycle
只有 !name	没有包含项，启动失败

Interface 是需要显式选择的用户界面，例如 cli；Lifecycle 是后台服务，例如 mcp.lifecycle。没有可启用渠道时以退出码 1 结束。

Shell 中排除项应加引号，例如 '!mcp.lifecycle'。

后台服务

平台	安装方式	位置或行为
Linux	systemd 用户单元	${XDG_CONFIG_HOME:-~/.config}/systemd/user/bub-gateway.service
Windows	计划任务	任务名 Bub Gateway，当前用户登录时启动
macOS	不支持 --install	使用 launchd、tmux 或容器部署

Linux 单元使用 Restart=on-failure、RestartSec=5s 和 WantedBy=default.target；安装时执行 daemon-reload、enable 和 restart。

• 服务固定当前 Python 解释器、工作区和显式 --enable-channel 参数。
• 重复安装会替换现有单元或任务并重启。
• --uninstall 在服务不存在时也视为成功。
• Linux 注销后仍需运行时，执行 loginctl enable-linger "$USER"。

bub onboard

交互式生成配置并写入 BubFramework.config_file，默认为 ~/.bub/config.yml；不启动渠道。

bub onboard [OPTIONS] [PLUGIN_NAME]

参数	类型	默认值	说明
PLUGIN_NAME	文本	无	只运行指定插件的 onboard_config

不带插件名时依次运行内置模型配置和其他已注册插件的配置；指定插件名时跳过网关服务安装询问。

选择或操作	写入行为
OpenAI 兼容服务或本地端点	写入 openai:<model>、api_base 和 client_args.api_format: chat
OpenAI 官方 API 使用非官方地址	地址重置为 https://api.openai.com/v1
Base URL 留空	保留提供商默认地址，不写入空值
Base URL 显式输入	即使等于默认值也写入
API key 留空	保留当前地址的 key，或继续使用环境变量
Base URL 改变	清空此前填写的 key
选择 Codex	跳过模型发现，手动输入模型 ID

连接检查只调用模型列表端点，超时 10 秒，不验证工具调用能力。全部配置经过 configure.validate 后才写盘。

退出码	含义
0	已保存，或用户拒绝安装网关
1	配置校验、写入、插件解析或网关安装失败

bub install

安装插件到 Bub 管理的 uv 项目；不带参数时同步该项目。

bub install [OPTIONS] [SPECS]...

参数与选项	类型	默认值	说明
SPECS	位置参数	空	要安装的包或 Git 来源
--project	路径	$BUB_HOME/bub-project 或 ~/.bub/bub-project	插件项目目录；也可使用 BUB_PROJECT

包规格	解析为
package	PyPI 包名
package@ref	bub-contrib 的 packages/package 子目录，固定到 ref
owner/repo	https://github.com/owner/repo.git
https://github.com/owner/repo.git@ref	带前缀的 Git URL，保留 ref
git@... 或 https://...	加 git+ 前缀

owner/repo@ref 不受支持；为任意 GitHub 仓库固定版本时使用完整 URL。

命令	uv 调用
bub install（无规格）	uv sync --active --inexact
bub install <specs>	uv add --active <requirements>
bub uninstall <packages>	uv remove --active <packages>
bub update	uv sync --active --upgrade --inexact
bub update <packages>	uv sync --active --inexact --upgrade-package ...

前置条件：

• uv 位于 PATH、当前 Python scripts 目录或 ~/.local/bin。
• Bub 运行在虚拟环境中。
• 显式传入的 --project 目录必须存在。

前置条件不满足时以退出码 1 结束；uv 失败时返回 uv 的退出码。

bub uninstall

从托管项目卸载一个或多个插件，不修改系统 Python 或 Bub 自身所在环境。

bub uninstall [OPTIONS] PACKAGES...

参数与选项	类型	默认值	说明
PACKAGES	位置参数	必填	与项目声明一致的包名
--project	路径	$BUB_HOME/bub-project 或 ~/.bub/bub-project	插件项目目录；也可使用 BUB_PROJECT

bub update

升级托管项目中的插件；不带包名时升级全部依赖。

bub update [OPTIONS] [PACKAGES]...

参数与选项	类型	默认值	说明
PACKAGES	位置参数	全部依赖	只升级指定包
--project	路径	$BUB_HOME/bub-project 或 ~/.bub/bub-project	插件项目目录；也可使用 BUB_PROJECT

升级不会自动迁移插件配置或 Tape 数据。

bub login codex

通过 Codex CLI 配置 ChatGPT 套餐凭据。

bub login codex [OPTIONS]

选项	类型	默认值	说明
--executable	文本	codex	Codex CLI 可执行文件
--device-auth	开关	关闭	使用设备授权流程
--codex-home	路径	$CODEX_HOME 或 ~/.codex	凭据目录

成功输出：

login: ok
account_id: <id>
Use BUB_MODEL=codex:<model> for ChatGPT plan access.

使用时设置 BUB_MODEL=codex:<model>，不要同时设置 BUB_API_KEY。失败时输出 login: failed: ... 并以退出码 1 结束。

bub plugins

列出已发现的插件及其包和版本号。

bub plugins [OPTIONS] [NAMES]...

参数与选项	类型	默认值	说明
NAMES	文本	全部插件	bub entry-point 组中的插件名
--version-only	开关	关闭	每行只输出一个插件的版本号

默认每行输出 name distribution version；内置 Hook 显示为 builtin，加载失败的插件附带 (failed: <error>)。名称不存在时以退出码 1 结束。

--version-only 在插件没有包元数据时输出 -。

bub hooks

打印 Hook 实现映射；该命令隐藏且不启动渠道。

bub hooks

<hook>: <implementation>, <implementation>

实现按 pluggy 注册顺序输出，Hook 名按字母排序；没有实现时输出 (no hook implementations)。该顺序不是实际执行顺序。

退出码

场景	退出码
命令成功	0
Typer 参数错误	2
缺少 app 可选依赖	1，进程在 Typer 前退出
没有可启用渠道、插件失败、配置失败	1
bub install / uninstall / update 的 uv 失败	uv 的退出码

bub run 的模型错误可能只写入日志并返回回退文本，因此脚本还应检查 stderr 和实际输出。