> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# ElevenLabs CLI

## 概览

ElevenLabs CLI 可让你从终端访问 ElevenLabs 智能体，提供新的管理方式：

* 在版本控制系统中将智能体存储为代码
* 设置 CI/CD 集成以自动部署智能体
* 让编程智能体访问和管理语音智能体

> **想直接查看代码？**
>
> 在 [GitHub 查看完整源代码并参与贡献](https://github.com/elevenlabs/cli)。

> **无需安装**
>
> 如果使用 Claude 或其他 MCP 客户端，[托管 MCP 服务器](/docs/zh/eleven-agents/operate/hosted-mcp)可提供智能体管理工具，无需本地安装。需要将智能体纳入版本控制时使用 CLI；需要对话式管理时使用托管 MCP 服务器。

## 安装

推荐使用 Homebrew（macOS）和 Scoop（Windows）安装，它们会提供独立二进制文件。

**`Homebrew（macOS）`**

```bash title="Homebrew（macOS）"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop（Windows）`**

```powershell title="Scoop（Windows）"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> 正在使用 AI 编程助手？在项目中运行 `elevenlabs generate-skills`，即可将每个命令组的
> `SKILL.md` 写入 `skills/`，无需粘贴文档，助手就能了解 CLI 的完整功能。使用 `--output-dir`
> 可将其放到其他位置。该命令会读取 CLI 内置的 API 定义，因此无需 API 密钥且可离线运行——还能始终与已安装的 CLI 版本保持同步。

安装后，`elevenlabs` 命令将在终端中全局可用。

## 快速开始

### 初始化新项目

```bash
elevenlabs agents init
```

这会创建包含配置目录和注册表文件的项目结构。

### 使用 ElevenLabs 进行身份验证

```bash
elevenlabs auth login
```

这会打开浏览器窗口，通过 OAuth 进行身份验证。CLI 会验证凭据并安全存储。

### 创建第一个智能体

```bash
elevenlabs agents add "My Assistant" --template assistant
```

这会使用助手模板创建新的智能体配置。

### 推送到 ElevenLabs 平台

```bash
elevenlabs agents push
```

这会将本地智能体配置上传到 ElevenLabs 平台。

## 项目结构

CLI 会创建结构化项目目录：

```
your_project/
├── agents.json              # Central agent configuration registry
├── tools.json               # Tool definitions registry
├── tests.json               # Test definitions registry
├── agent_configs/           # Agent configuration files
├── tool_configs/            # Tool configuration files
└── test_configs/            # Test configuration files
```

## 身份验证

`elevenlabs auth login` 会将凭据存储在操作系统的密钥链中——macOS 上为 Keychain、Windows 上为凭据管理器、Linux 上为 Secret Service。若没有可用的密钥链，CLI 会回退到权限为 `0600` 的 `~/.config/elevenlabs/auth-keyring.json`。运行 `elevenlabs auth status` 查看正在使用的来源，运行 `elevenlabs auth logout` 删除已存储的条目。

对于 CI，请在环境变量或 `.env` 文件中设置 `ELEVENLABS_API_KEY`，而非登录。

### 身份验证命令

**`登录`**

```bash title="登录"
elevenlabs auth login
```

**`退出登录`**

```bash title="退出登录"
elevenlabs auth logout
```

## 智能体管理

### 创建智能体

使用预构建模板创建智能体：

```bash
elevenlabs agents add "Agent Name" [options]
```

**选项：**

* `--template <type>`：从可用模板中选择（默认：default）
* `--skip-upload`：仅在本地创建，不上传到平台

**示例：**

```bash
elevenlabs agents add "Customer Support Bot" --template customer-service
```

### 模板

CLI 为常见用例提供 6 个预构建模板：

#### default

包含所有可用字段、合理默认值、完整语音/文本支持、组件自定义和评估标准的完整配置。

#### minimal

仅包含基本提示词、语言、TTS 和对话设置等必要字段。

#### voice-only

针对语音交互优化，禁用文本输入，并提供高级语音设置。

#### text-only

以文本为重点的对话，禁用语音功能。

#### customer-service

专业且富有同理心的提示词、低温度值（0.1）、30 分钟时长和评估标准。

#### assistant

通用 AI 助手，具备均衡的创造力（温度值 0.3）和多样化的语音/文本支持。

### 模板命令

**`列出可用模板`**

```bash title="列出可用模板"
elevenlabs agents templates list
```

**`显示模板配置`**

```bash title="显示模板配置"
elevenlabs agents templates show <template>
```

### 同步

使本地配置与 ElevenLabs 平台保持同步：

**`推送所有智能体`**

```bash title="推送所有智能体"
elevenlabs agents push
```

**`预览更改（试运行）`**

```bash title="预览更改（试运行）"
elevenlabs agents push --dry-run
```

### 状态和监控

**`检查智能体状态`**

```bash title="检查智能体状态"
elevenlabs agents status
```

### 导入和导出

**`导入现有智能体`**

```bash title="导入现有智能体"
elevenlabs agents pull
```

**`导入指定智能体`**

```bash title="导入指定智能体"
elevenlabs agents pull --agent <agent_id>
```

**`更新智能体`**

```bash title="更新智能体"
elevenlabs agents pull --update
```

**`列出所有智能体`**

```bash title="列出所有智能体"
elevenlabs agents list
```

> **Note**
>
> 默认情况下，`elevenlabs agents pull` 会跳过本地已存在的智能体。使用 `--update`
> 标志可用在浏览器中或通过 API 进行的远程更改覆盖本地配置。

## 工具管理

CLI 支持两类用于扩展智能体能力的工具：

### Webhook 工具

带有身份验证和超时配置的 HTTP API 集成：

```bash
elevenlabs tools add "API Integration" --type "webhook" --config-path ./config.json
```

### 客户端工具

直接的客户端集成：

```bash
elevenlabs tools add "Client Function" --type "client" --config-path ./config.json
```

## 组件生成

生成用于 Web 集成的 HTML 嵌入代码：

```bash
elevenlabs agents widget embed <agent_id>
```

输出的 HTML 代码如下：

```html
<elevenlabs-convai agent-id="agent_id_here"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async></script>
```

## 配置文件

### 智能体配置结构

每个智能体配置包含：

```json
{
  "name": "Agent Name",
  "conversation_config": {
    "agent": {
      "language": "en",
      "prompt": {
        "prompt": "You are a helpful AI assistant.",
        "llm": "gemini-2.5-flash",
        "temperature": 0.0
      }
    },
    "tts": {
      "model_id": "eleven_turbo_v2",
      "voice_id": "cjVigY5qzO86Huf0OWal",
      "agent_output_audio_format": "pcm_16000"
    },
    "asr": {
      "provider": "scribe_realtime",
      "quality": "high",
      "user_input_audio_format": "pcm_16000"
    },
    "conversation": {
      "text_only": false,
      "max_duration_seconds": 600,
      "client_events": ["audio", "interruption"]
    }
  },
  "platform_settings": {
    "widget": {
      "variant": "full",
      "placement": "bottom-right"
    }
  },
  "tags": []
}
```

### CI/CD 流水线集成

```yml
# In your GitHub Actions workflow
- name: Deploy ElevenAgents agents
  run: |
    npm install -g @elevenlabs/cli
    export ELEVENLABS_API_KEY=${{ secrets.ELEVENLABS_API_KEY }}
    elevenlabs agents push --dry-run  # Preview changes
    elevenlabs agents push            # Deploy
    elevenlabs agents status          # Verify deployment
```