> 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

## Overview

The ElevenLabs CLI allows you to access your ElevenLabs agents from your terminal, unlocking new ways to manage them:

* Store agents as code in your version control system
* Set up CI/CD integration to automatically deploy your agents
* Let your coding agent access and manage your voice agents

> **Prefer to jump straight to the code?**
>
> Find the [complete source code and contribute on GitHub](https://github.com/elevenlabs/cli).

> **No install required**
>
> If you work from Claude or another MCP client, the [hosted MCP server](/docs/eleven-agents/operate/hosted-mcp) offers agent management tools with no local
> installation. Use the CLI when you want agents in version control; use the hosted MCP server for
> conversational management.

## Installation

Homebrew (macOS) and Scoop (Windows) are the recommended install methods and ship a standalone binary.

**`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**
>
> Working with an AI coding assistant? Run `elevenlabs generate-skills` in your project to write a
> `SKILL.md` for every command group into `skills/`, so your assistant knows the CLI's full surface
> without you pasting docs. Use `--output-dir` to put them elsewhere. This reads the CLI's own
> embedded API definition, so it needs no API key and works offline — and it stays in step with
> whichever CLI version you have installed.

After installation, the `elevenlabs` command will be available globally in your terminal.

## Quick start

### Initialize a new project

```bash
elevenlabs agents init
```

This creates the project structure with configuration directories and registry files.

### Authenticate with ElevenLabs

```bash
elevenlabs auth login
```

This will open up a browser window to authenticate via OAuth. The CLI will verify the credentials and store them securely.

### Create your first agent

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

This creates a new agent configuration using the assistant template.

### Push to ElevenLabs platform

```bash
elevenlabs agents push
```

This uploads your local agent configuration to the ElevenLabs platform.

## Project structure

The CLI creates a structured project directory:

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

## Authentication

`elevenlabs auth login` stores credentials in your operating system's keyring — Keychain on macOS,
Credential Manager on Windows, and the Secret Service on Linux. Where no keyring is available, the
CLI falls back to `~/.config/elevenlabs/auth-keyring.json` with `0600` permissions. Run
`elevenlabs auth status` to see which source is in use, and `elevenlabs auth logout` to remove the
stored entry.

For CI, set `ELEVENLABS_API_KEY` in the environment or a `.env` file instead of logging in.

### Authentication commands

**`Login`**

```bash title="Login"
elevenlabs auth login
```

**`Logout`**

```bash title="Logout"
elevenlabs auth logout
```

## Agent management

### Creating agents

Create agents using pre-built templates:

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

**Options:**

* `--template <type>`: Choose from available templates (default: default)
* `--skip-upload`: Create locally without uploading to platform

**Example:**

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

### Templates

The CLI provides six pre-built templates for common use cases:

#### default

Complete configuration with all available fields, sensible defaults, full voice/text support, widget customization, and evaluation criteria.

#### minimal

Essential fields only including basic prompt, language, TTS, and conversation settings.

#### voice-only

Optimized for voice interactions with disabled text input and advanced voice settings.

#### text-only

Text-focused conversations with disabled voice features.

#### customer-service

Professional empathetic prompts, low temperature (0.1), 30-minute duration, and evaluation
criteria.

#### assistant

General-purpose AI assistant with balanced creativity (temperature 0.3) and versatile voice/text support.

### Template commands

**`List available templates`**

```bash title="List available templates"
elevenlabs agents templates list
```

**`Show template configuration`**

```bash title="Show template configuration"
elevenlabs agents templates show <template>
```

### Synchronization

Keep your local configurations synchronized with the ElevenLabs platform:

**`Push all agents`**

```bash title="Push all agents"
elevenlabs agents push
```

**`Preview changes (dry run)`**

```bash title="Preview changes (dry run)"
elevenlabs agents push --dry-run
```

### Status and monitoring

**`Check agent status`**

```bash title="Check agent status"
elevenlabs agents status
```

### Import and export

**`Import existing agents`**

```bash title="Import existing agents"
elevenlabs agents pull
```

**`Import specific agent`**

```bash title="Import specific agent"
elevenlabs agents pull --agent <agent_id>
```

**`Update agents`**

```bash title="Update agents"
elevenlabs agents pull --update
```

**`List all agents`**

```bash title="List all agents"
elevenlabs agents list
```

> **Note**
>
> By default, `elevenlabs agents pull` skips agents that already exist locally. Use the `--update`
> flag to override local configurations with remote changes made in the browser or via the API.

## Tool management

The CLI supports two types of tools for extending agent capabilities:

### Webhook tools

HTTP API integrations with authentication and timeout configuration:

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

### Client tools

Direct client-side integrations:

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

## Widget generation

Generate HTML embed code for web integration:

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

This outputs HTML code like:

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

## Configuration files

### Agent configuration structure

Each agent configuration includes:

```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 pipeline integration

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

> ElevenLabs provides APIs and SDKs for text to speech, voice cloning, speech to text, sound effects, voice isolator, voice changer, and conversational AI agents. Build voice-enabled applications with lifelike audio generation.