> 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 提示

Doubao Dev CLI 是豆包应用插件的命令行工具，可用于完成项目初始化、登录、开发调试、产物校验和云构建等工作。本文说明安装、登录验证和首次项目初始化。

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

:::

## 环境要求

- Node.js `>= 22.13.0`

## 安装 CLI

使用公开 npm 包全局安装：

```bash
npm install -g @doubao-dev/cli
```

安装完成后，确认命令可用：

```bash
dbx --version
dbx --help
```

如果终端提示找不到 `dbx`，请重新打开终端；若问题仍然存在，检查 npm 的全局 bin 目录是否已加入系统 `PATH`。

## 登录

首次使用需要登录豆包开发者平台账号：

```bash
dbx auth login
```

命令会展示或打开授权页面。完成授权后，检查登录状态：

```bash
dbx auth status
```

## 初始化项目

进入准备存放项目的文件夹，运行下面的命令。CLI 会新建 `my-app` 目录，请确保没有同名目录：

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

按照终端提示选择开发工具并完成登录，CLI 会帮你：

- 创建 Manifest、运行态 Skill 和项目规则；
- 安装与当前 CLI 版本匹配的 Agent Skill；
- 在新项目根目录创建前端脚手架并安装依赖；
- 检查并按需引导完成登录。

如果通过脚本或 AI 的非交互终端创建项目，请先登录，并在命令中写明新目录和 `--agent <agent>`。已有项目只需更新开发 Skill 时，在项目根目录运行 `dbx skills sync`。

### 项目目录结构

完成初始化后，一个完整的豆包应用插件项目通常如下：

```bash
.
├── AGENTS.md
├── manifest.yaml      # 配置：基础信息、工具定义、UI 绑定关系
├── package.json       # 依赖
├── skill              # 业务 Skill
│   └── SKILL.md
├── src
│   ├── app.config.ts   # 应用配置
│   ├── app.ts
│   ├── pages           # 全页
│   └── widgets         # 卡片
└── tsconfig.json
```

其中 `manifest.yaml`、`skill/SKILL.md` 和前端工程共同构成一个可构建的应用插件版本。MCP Server 可以与项目同仓库，也可以独立部署；无论代码放在哪里，都需要在 `manifest.yaml` 中配置可访问的 MCP endpoint。

## 升级

执行更新命令更新到最新公开版本：

```bash
dbx upgrade
```

更新后重新确认版本和帮助信息：

```bash
dbx --version
dbx --help
```

建议 CLI、项目初始化的 Agent Skill 和前端依赖保持在同一发布周期；遇到命令参数、模板或调试行为不符合预期时，优先升级 CLI，再执行 `dbx skills sync` 更新项目中的开发 Skill。

## 常见问题

### 安装后找不到命令

通常是 npm 全局 bin 目录未加入 `PATH`。重新打开终端后重试；仍失败时，检查 npm 的全局安装目录和 shell 配置。

### Node.js 版本不满足要求

升级 Node.js 至 `22.13.0` 或更高版本后，重新执行安装命令。不要通过忽略版本检查继续使用旧版本 Node.js。

### 登录成功后仍提示未登录

先执行：

```bash
dbx auth status
```

如果登录态过期，重新执行 `dbx auth login`。在 CI、容器或远程开发机中，登录命令和后续开发命令必须在同一用户环境中执行。

### 初始化时无法安装依赖或创建前端工程

先确认 Node.js、npm 和网络可用，并检查是否已经存在同名目录。如果想先创建工程、稍后再安装依赖，可以添加 `--no-install-deps`。

## 下一步

安装并登录后，阅读[《CLI 命令总览》](/apps-plugin/docs/development-tools/commands.md)了解可用能力；首次开发应用插件时，继续阅读[《本地调试与预览》](/apps-plugin/docs/development-tools/local-debugging.md)，完成 MCP、Skill、Manifest 与前端的联调。
