> 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.

# CLI 命令总览

:::info 提示

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

<div hidden data-lark-callout-end></div>

:::

## 命令速览

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

## 全局选项

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

例如：

```bash
dbx build --help
```

## 初始化与升级

### 初始化项目

```bash
dbx init my-app
cd my-app
```

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

### 升级 CLI

```bash
dbx upgrade --check
dbx upgrade
```

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

## 认证

### 登录

```bash
dbx auth login
```

### 查看登录状态

```bash
dbx auth status
```

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

## 本地调试

### 启动调试控制台

```bash
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`：

```text
desktop
page "<page-url>"
```

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

### 推送指定卡片

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

```text
widget <widget-id>
```

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

### 停止调试服务

```bash
dbx dev stop
```

## 配置校验与云构建

### 校验 Manifest

```bash
dbx check --file ./manifest.yaml
```

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

### 创建测试版本

```bash
dbx build
```

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

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

如果要构建其他目录中的项目，用 `--project` 指定项目根目录：

```bash
dbx build --project <project-path>
```

需要给云构建传入环境变量时，用 `--env <path>` 指定普通变量文件，`--secret-env <path>` 指定秘密变量文件。文件名须以 `.env` 开头，相对路径从项目根目录算起。示例见[打包与提审](/apps-plugin/docs/release/package-and-submit.md)。

### 创建正式版本

以下两种用法任选其一：

```bash
dbx build --release
dbx build --release 1.2.3
```

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

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

### 查询云构建状态

```bash
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`。

### 同步应用级平台配置

```bash
dbx config sync
dbx config sync business-templates
```

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

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

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

### 查询 Sandbox 信息

```bash
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

```bash
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>`。

## 推荐使用顺序

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

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