CLI 命令总览
下面按开发流程介绍常用的 dbx 命令。除初始化外,请在项目根目录运行这些命令。想查看某条命令的完整用法,可以在命令后加 --help。
命令速览
全局选项
例如:
初始化与升级
初始化项目
先进入准备存放项目的文件夹,再运行上面的命令。CLI 会新建 my-app 目录,并生成前端工程、Manifest 和 Skill;请使用一个还没有创建的目录名。通过脚本或 AI 的非交互终端创建项目时,还需要用 --agent <agent> 指定开发工具。项目结构可参考《CLI 安装与配置》。
升级 CLI
第一条命令只检查是否有更新;第二条命令执行更新并刷新配套 Skill。更新后建议重新执行 dbx --help,以当前帮助输出为准。
认证
登录
查看登录状态
登录态失效时重新执行登录命令。不要在日志、截图或代码仓库中记录授权信息。
本地调试
启动调试控制台
dbx dev 用于启动本地调试服务。使用项目配置的 MCP 地址时,直接运行 dbx dev 即可;需要临时换一个地址时,再添加上面的 --mcp-endpoint。
服务就绪后,在控制台输入 web 或打开终端显示的完整 Web 地址,即可预览。也可以让 AI 执行同一条命令并保持服务运行;如果还需要它在控制台中连接真机或推送卡片,请让它使用交互式终端(TTY)。
常用参数:
打开指定页面
在已启动的 dev 交互控制台中执行 desktop,按提示连接真机,再执行 page:
将 pages 列出的完整页面地址传给 page,页面参数写在地址的查询参数中。也可以直接输入 page,再从列表中选择页面。连接多台设备时,可用 --device-id <id> 指定目标设备。
推送指定卡片
在已连接真机的 dev 交互控制台中执行:
可使用 --data <json> 传递卡片渲染数据,使用 --device-id <id> 指定已连接的设备。省略 widget-id 时可从 widgets 列表中选择;指定的 ID 必须与前端 app.config.ts 注册的卡片 ID 一致。
停止调试服务
配置校验与云构建
校验 Manifest
校验 Manifest 的格式、字段和协议约束。修改工具、实体、权限、MCP 配置或卡片绑定后,应先执行此命令。
创建测试版本
运行后,CLI 会检查项目根目录的 manifest.yaml、skill/ 和前端源码,同步项目中的平台配置,再上传文件并创建测试版本。请先确认 manifest.yaml 的 app_key 填写了正确的 AppID。
命令默认会等待云构建完成,最多等待 300 秒。需要等待更久时,用 --timeout-seconds <n> 调整时长;想提交后立即返回,则使用 --no-wait,此时不能同时指定 --timeout-seconds。即使等待超时,云端仍会继续构建。
如果要构建其他目录中的项目,用 --project 指定项目根目录:
需要给云构建传入环境变量时,用 --env <path> 指定普通变量文件,--secret-env <path> 指定秘密变量文件。文件名须以 .env 开头,相对路径从项目根目录算起。示例见打包与提审。
创建正式版本
以下两种用法任选其一:
准备提审时,使用 --release 创建正式版本。可以让平台自动生成版本号,也可以像第二条命令一样指定 x.y.z 格式的版本号。命令返回的 version_tag 用于查询构建状态;提审和发布仍需在开发者平台完成。
正式上传前,确认 manifest.yaml 中的 AppID 和 MCP endpoint 均为正式可用配置;云构建不能访问仅在本机监听的 MCP 地址。
查询云构建状态
该命令只查询一次。构建状态统一为 queued、building、succeeded、failed 或 unknown;查询到远端失败状态仍正常退出。构建失败时请保留 log_id、version_tag 和错误信息用于排查。
构建成功后,终端会显示版本详情页、应用详情页和豆包调试会话地址;JSON 中对应 version_detail_url、app_detail_url 和 doubao_debug_conversation_url。--json 模式只在标准输出写入一个 JSON 对象;使用 --no-wait 时还会提供 argv 数组形式的 next_actions。
同步应用级平台配置
直接运行 dbx config sync 会同步项目中支持的平台配置,目前支持项目根目录的 business-templates.yaml。如果没有这个文件,命令会跳过它,平台已有配置会保留。
这些配置由应用的所有版本共用,创建测试版本也可能更新它们。回滚版本时,平台配置不会跟着回滚。
如果指定了 business-templates,请先准备好 business-templates.yaml,否则命令会报错并返回退出码 1;填写不支持的配置类型时返回退出码 2。配置校验通过后才会上传。从本地 YAML 删除模板,不会删除平台上已有的模板。
查询 Sandbox 信息
在项目目录中运行即可查询该项目的 Sandbox;CLI 会从当前目录向上查找 manifest.yaml。也可以用 --project 指定项目根目录,找不到项目时会报错。
Sandbox 信息从平台查询,默认显示 AppID,并提示是否已配置 Secret。需要查看 Secret 时再添加 --include-secret,不要将它写入日志、截图或代码仓库。
启动 MCP Demo
交互式终端可以省略 Demo 名称后选择;非交互终端或 JSON 模式必须明确指定 taxi 或 milk-tea。
JSON 输出与退出码
构建结果中的 config_sync_results 与版本构建状态相互独立,配置同步成功不代表版本构建成功。错误 JSON 会提供稳定的 error.code。
dbx build 等待到构建失败时退出 1,JSON 中的 error.code 为 DBX_BUILD_FAILED,构建详情位于 details。dbx build status <version> --json 成功查询到失败构建时仍退出 0,通过 state: "failed" 和 build_error 表达远端失败,不返回 error.code;可结合 error_info_file(如有)和 log_id 排查。
项目参数
build(含 --release 选项和 status 子命令)、config sync 和 sandbox info 使用 --project <path> 指定项目;dev、check 和 eval 的项目参数为 --project-path <path>。
推荐使用顺序
云构建成功只表示产物构建完成。审核、灰度和正式发布请按开发者平台的发布流程继续操作。