For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/development-tools/commands.md.

CLI 命令总览

提示

下面按开发流程介绍常用的 dbx 命令。除初始化外,请在项目根目录运行这些命令。想查看某条命令的完整用法,可以在命令后加 --help。

命令速览

阶段命令用途
初始化init初始化项目配置、运行态 Skill 和前端工程。
认证与升级auth login、auth status、upgrade登录、检查登录态、更新 CLI 及配套资源。
本地调试dev、dev stop启动或停止调试服务;在 dev 交互控制台中连接真机、打开页面和推送卡片。
配置校验check --file校验 Manifest 或业务模板。
产物与云构建build、build --release、build status创建测试/正式版本并查询云构建。
平台配置config sync同步业务模板等应用级平台配置。
Sandboxsandbox info查询当前项目的 Sandbox 信息。
MCP Demomcp demo启动内置 Taxi 或 Milk Tea Demo。

全局选项

选项说明
--json输出机器可读 JSON,适合脚本或 Agent 解析;dbx dev 不支持。
-d, --debug输出更多调试信息。
--help查看当前命令的参数、说明和示例。

例如:

dbx build --help

初始化与升级

初始化项目

dbx init my-app
cd my-app

先进入准备存放项目的文件夹,再运行上面的命令。CLI 会新建 my-app 目录,并生成前端工程、Manifest 和 Skill;请使用一个还没有创建的目录名。通过脚本或 AI 的非交互终端创建项目时,还需要用 --agent <agent> 指定开发工具。项目结构可参考《CLI 安装与配置》。

升级 CLI

dbx upgrade --check
dbx upgrade

第一条命令只检查是否有更新;第二条命令执行更新并刷新配套 Skill。更新后建议重新执行 dbx --help,以当前帮助输出为准。

认证

登录

dbx auth login

查看登录状态

dbx auth status

登录态失效时重新执行登录命令。不要在日志、截图或代码仓库中记录授权信息。

本地调试

启动调试控制台

dbx dev --mcp-endpoint <mcp-endpoint>

dbx dev 用于启动本地调试服务。使用项目配置的 MCP 地址时,直接运行 dbx dev 即可;需要临时换一个地址时,再添加上面的 --mcp-endpoint。

服务就绪后,在控制台输入 web 或打开终端显示的完整 Web 地址,即可预览。也可以让 AI 执行同一条命令并保持服务运行;如果还需要它在控制台中连接真机或推送卡片,请让它使用交互式终端(TTY)。

常用参数:

参数说明
--mcp-endpoint <url>临时覆盖 Manifest 中的 MCP endpoint。
--project-path <path>指定豆包应用插件项目目录。
--manifest <path>指定 Manifest 文件,默认使用项目根目录的 manifest.yaml;相对路径从 --project-path 指定的目录算起。
--skill <path>指定 Skill 所在目录,默认使用项目的 skill/;会读取该目录及子目录中的所有 SKILL.md。相对路径从 --project-path 指定的目录算起。
--host [host]指定本机调试地址。只写 --host 时会提示你选择地址,省略此选项则自动选择。
--verbose显示调试服务启动、运行和停止时的详细日志。

打开指定页面

在已启动的 dev 交互控制台中执行 desktop,按提示连接真机,再执行 page:

desktop
page "<page-url>"

将 pages 列出的完整页面地址传给 page,页面参数写在地址的查询参数中。也可以直接输入 page,再从列表中选择页面。连接多台设备时,可用 --device-id <id> 指定目标设备。

推送指定卡片

在已连接真机的 dev 交互控制台中执行:

widget <widget-id>

可使用 --data <json> 传递卡片渲染数据,使用 --device-id <id> 指定已连接的设备。省略 widget-id 时可从 widgets 列表中选择;指定的 ID 必须与前端 app.config.ts 注册的卡片 ID 一致。

停止调试服务

dbx dev stop

配置校验与云构建

校验 Manifest

dbx check --file ./manifest.yaml

校验 Manifest 的格式、字段和协议约束。修改工具、实体、权限、MCP 配置或卡片绑定后,应先执行此命令。

创建测试版本

dbx build

运行后,CLI 会检查项目根目录的 manifest.yaml、skill/ 和前端源码,同步项目中的平台配置,再上传文件并创建测试版本。请先确认 manifest.yaml 的 app_key 填写了正确的 AppID。

命令默认会等待云构建完成,最多等待 300 秒。需要等待更久时,用 --timeout-seconds <n> 调整时长;想提交后立即返回,则使用 --no-wait,此时不能同时指定 --timeout-seconds。即使等待超时,云端仍会继续构建。

如果要构建其他目录中的项目,用 --project 指定项目根目录:

dbx build --project <project-path>

需要给云构建传入环境变量时,用 --env <path> 指定普通变量文件,--secret-env <path> 指定秘密变量文件。文件名须以 .env 开头,相对路径从项目根目录算起。示例见打包与提审。

创建正式版本

以下两种用法任选其一:

dbx build --release
dbx build --release 1.2.3

准备提审时,使用 --release 创建正式版本。可以让平台自动生成版本号,也可以像第二条命令一样指定 x.y.z 格式的版本号。命令返回的 version_tag 用于查询构建状态;提审和发布仍需在开发者平台完成。

正式上传前,确认 manifest.yaml 中的 AppID 和 MCP endpoint 均为正式可用配置;云构建不能访问仅在本机监听的 MCP 地址。

查询云构建状态

dbx build status <version>

该命令只查询一次。构建状态统一为 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
dbx config sync business-templates

直接运行 dbx config sync 会同步项目中支持的平台配置,目前支持项目根目录的 business-templates.yaml。如果没有这个文件,命令会跳过它,平台已有配置会保留。

这些配置由应用的所有版本共用,创建测试版本也可能更新它们。回滚版本时,平台配置不会跟着回滚。

如果指定了 business-templates,请先准备好 business-templates.yaml,否则命令会报错并返回退出码 1;填写不支持的配置类型时返回退出码 2。配置校验通过后才会上传。从本地 YAML 删除模板,不会删除平台上已有的模板。

查询 Sandbox 信息

dbx sandbox info
dbx sandbox info --project <project-path>
dbx sandbox info --include-secret

在项目目录中运行即可查询该项目的 Sandbox;CLI 会从当前目录向上查找 manifest.yaml。也可以用 --project 指定项目根目录,找不到项目时会报错。

Sandbox 信息从平台查询,默认显示 AppID,并提示是否已配置 Secret。需要查看 Secret 时再添加 --include-secret,不要将它写入日志、截图或代码仓库。

启动 MCP Demo

dbx mcp demo taxi
dbx mcp demo milk-tea

交互式终端可以省略 Demo 名称后选择;非交互终端或 JSON 模式必须明确指定 taxi 或 milk-tea。

JSON 输出与退出码

退出码含义
0命令成功;build status 查询到远端失败状态也返回 0。
1校验、网络、配置同步、构建失败或等待超时。
2参数或命令用法错误。
130用户中断。

构建结果中的 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>。

推荐使用顺序

init
  -> auth login
  -> 编写 Manifest、Skill、MCP 与前端代码
  -> check --file manifest.yaml
  -> dev
  -> build(测试版本)
  -> build --release [version](正式、可提审版本;版本号可省略)

云构建成功只表示产物构建完成。审核、灰度和正式发布请按开发者平台的发布流程继续操作。