cli

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #typescript #llm #go #rust #docker #macos #nodejs #awesome #awesome-list #pytorch #security

(★ 74)

Command Line Interface to interact with ElevenLabs voice agents

cli Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ElevenLabs CLI - Agents as Code

![hero](https://raw.githubusercontent.com/elevenlabs/cli/main/assets/Cover.png)

# ElevenLabs CLI

Build multimodal agents with the [ElevenLabs platform](https://elevenlabs.io/docs/agents-platform/overview).

Manage ElevenLabs with local configuration files. This tool is an experimental exploration of treating agents as code, with features like templates and automatic pushing.

## Features

- **Agent Configuration**: Full ElevenLabs agent schema support
- **Templates**: Pre-built templates for common use cases
- **Smart Updates**: Hash-based change detection
- **Import/Export**: Fetch existing agents and tools from workspace
- **Tool Management**: Import and manage tools from ElevenLabs workspace
- **Branch Support**: Pull/push specific agent branches, CI/CD-friendly multi-branch workflows
- **Widget Generation**: HTML widget snippets
- **Secure Storage**: OS keychain integration with secure file fallback

## Installation

```bash
# Global installation
pnpm install -g @elevenlabs/cli
# OR
npm install -g @elevenlabs/cli

# One-time usage
pnpm dlx @elevenlabs/cli agents init
# OR
npx @elevenlabs/cli agents init
```

## Setup

### Authentication

```bash
elevenlabs auth login
```

Or set environment variable:

```bash
export ELEVENLABS_API_KEY="your_api_key_here"
```

> **Note**: For now, your API key must be unrestricted to work with the CLI, as ElevenLabs-restricted keys are not available yet.

### Check Status

```bash
elevenlabs auth whoami
```

### Set Residency Location

Configure the API residency for isolated regions:

```bash
# Set to EU residency (uses api.eu.elevenlabs.io)
elevenlabs auth residency eu-residency

# Set to India residency (uses api.in.elevenlabs.io)
elevenlabs auth residency in-residency

# Set to US/Global (uses api.elevenlabs.io or api.us.elevenlabs.io)
elevenlabs auth residency global  # or 'us'
```

### Logout

```bash
elevenlabs auth logout
```

## Quick Start

```bash
# 1. Initialize project
elevenlabs agents init

# Or override existing configuration
elevenlabs agents init --override

# 2. Login with API key
elevenlabs auth login

# 3. Create agent with template
elevenlabs agents add "Support Bot" --template customer-service

# 4. Edit configuration (agent_configs/support_bot.json)

# 5. Sync to ElevenLabs
elevenlabs agents push
```

## Directory Structure

```
your_project/
├── agents.json              # Central configuration (includes branch mappings)
├── tools.json               # Tool configurations
├── tests.json               # Test configurations
├── agent_configs/           # Agent configuration files
│   ├── My-Agent.json        # Main branch config
│   └── My-Agent.staging.json # Branch config (auto-created by --all-branches)
├── tool_configs/            # Tool configurations
└── test_configs/            # Test configurations
```

## Commands

### Initialize Project

The `elevenlabs agents init` command sets up the project structure for managing ElevenLabs agents:

```bash
elevenlabs agents init                    # Initialize in current directory
elevenlabs agents init ./my-project       # Initialize in specific directory
elevenlabs agents init --override         # Override existing files and recreate from scratch
```

**Default behavior**: When you run `elevenlabs agents init`, it will:
- Create missing files and directories
- Skip existing files (shown as "skipped" in output)
- Preserve your existing configuration

**Override mode** (`--override`): When you need to reset your project:
- Overwrites all configuration files
- Recreates directory structure from scratch
- **Warning**: This will delete all existing configurations in `agent_configs/`, `tool_configs/`, and `test_configs/`

Use `--override` when:
- You want to start fresh with a clean configuration
- Your configuration has become inconsistent
- You're setting up a new environment and want to ensure clean state

### Core Commands

```bash

# Authentication
elevenlabs auth login
elevenlabs auth logout
elevenlabs auth whoami

# Create agent from template
elevenlabs agents add "Agent Name" [--template customer-service] [--output-path path]

# Create agent from existing config file
elevenlabs agents add [name] --from-file existing-config.json [--output-path path]

# Create webhook tool
elevenlabs tools add-webhook "Tool Name" [--config-path path]

# Create client tool
elevenlabs tools add-client "Tool Name" [--config-path path]

# Push changes (main + all registered branches)
elevenlabs agents push [--agent <agent_id>] [--dry-run]

# Push to a specific branch
elevenlabs agents push --agent <agent_id> --branch <branch_name_or_id>

# List branches for an agent
elevenlabs agents branches list --agent <agent_id> [--include-archived]

# Sync tools
elevenlabs tools push [--tool "Tool Name"] [--dry-run]

# Sync tests
elevenlabs tests push [--dry-run] [--config-dir test_configs]

# Check status
elevenlabs agents status [--agent "Agent Name"]

# Pull agents from ElevenLabs
elevenlabs agents pull [--search "term"] [--update] [--dry-run]

# Pull from a specific branch
elevenlabs agents pull --agent <agent_id> --branch <branch_name_or_id>

# Pull all branches for each agent (stores as separate config files)
elevenlabs agents pull --all --all-branches

# Pull tools from ElevenLabs
elevenlabs tools pull [--search "term"] [--tool "tool-name"] [--dry-run] [--output-dir tool_configs]

# Import tests from ElevenLabs
elevenlabs tests pull [--output-dir test_configs] [--dry-run]

# Create and run test
elevenlabs tests add "Test Name" [--template basic-llm]

# Run tests
elevenlabs agents test "Agent Name"

# Generate widget HTML (includes server-location for isolated regions)
elevenlabs agents widget "Agent Name"

# List agents
elevenlabs agents list

# Delete agent (removes locally and from ElevenLabs)
elevenlabs agents delete <agent_id>

# Delete tool locally and from ElevenLabs
elevenlabs tools delete <tool_id>

# Delete all tools
elevenlabs tools delete --all

# Delete test locally and from ElevenLabs
elevenlabs tests delete <test_id>

# Delete all tests
elevenlabs tests delete --all

# Add componenents from [ui.elevenlabs.io](https://ui.elevenlabs.io)
elevenlabs components add "Component Name"
```

### Templates

```bash
# List available templates
elevenlabs agents templates list

# Show template details
elevenlabs agents templates show customer-service
```

## Available Templates

### `default`

Complete configuration with all available fields and sensible defaults. Includes full voice and text support, widget customization, evaluation criteria, and platform settings. Best for production deployments requiring comprehensive configuration.

### `minimal`

Minimal configuration with only essential fields. Contains basic agent prompt, language settings, TTS configuration, and conversation settings. Perfect for quick prototyping and simple use cases.

### `voice-only`

Optimized for voice-only conversations. Disables text input and focuses on voice interaction features. Includes advanced voice settings, turn management, and audio processing optimizations.

### `text-only`

Optimized for text-only conversations. Disables voice features and focuses on text-based interactions.

### `customer-service`

Pre-configured for customer service scenarios. Features professional, empathetic prompts with consistent responses (low temperature). Includes extended conversation duration (30 minutes), evaluation criteria for service quality, and customer-service tags.

### `assistant`

General purpose AI assistant configuration. Balanced creativity settings with helpful, knowledgeable prompts. Supports both voice and text interactions for versatile use cases like Q&A, explanations, and analysis tasks.

## Configuration Example

```json
{
  "name": "Support Bot",
  "conversation_config": {
    "agent": {
      "prompt": {
        "prompt": "You are a helpful customer service representative.",
        "llm": "gemini-2.5-flash",
        "temperature": 0.1
      },
      "language": "en"
    },
    "tts": {
      "model_id": "eleven_turbo_v2",
      "voice_id": "cjVigY5qzO86Huf0OWal"
    }
  },
  "tags": ["customer-service"]
}
```

## Common Workflows

**New Project:**

```bash
elevenlabs agents init
elevenlabs auth login
elevenlabs agents add "My Agent" --template assistant
elevenlabs agents push
```

**Import Existing from ElevenLabs:**

```bash
elevenlabs agents init
elevenlabs auth login
elevenlabs agents pull
elevenlabs agents push
```

**Update Local Agents with Remote Changes:**

```bash
# By default, 'agents pull' skips agents that already exist locally
# Use --update to override local configurations with remote changes
elevenlabs agents pull --update
```

Use `--update` when:
- You've made changes to an agent in the browser or via the API
- You want to sync remote changes to your local configuration
- Your local agent configuration is out of sync with ElevenLabs

**Create Agent from Local Config File:**

```bash
# You have an existing agent config file (e.g., my-template.json)
# Import it and register it with ElevenLabs
elevenlabs agents init
elevenlabs auth login
elevenlabs agents add --from-file my-template.json
# This will:
# - Upload the agent to ElevenLabs
# - Get an agent ID
# - Register it in agents.json
# - Save a copy to agent_configs/
```

**Import and Use Tools:**

```bash
elevenlabs agents init
elevenlabs auth login
elevenlabs tools pull
# Edit tool configs in tool_configs/
# Tools will have 'env' field - modify if needed
# Reference tools in your agent configurations
elevenlabs agents push
```

**Delete Agent:**

```bash
# List agents to find the agent ID
elevenlabs agents list

# Delete agent by ID (removes locally and from ElevenLabs)
elevenlabs agents delete agent_123456789
```

## Branch Workflows

Agent branches let you manage different configurations (e.g., staging vs production) alongside the main agent. Branch configs are stored as separate files in `agent_configs/` and tracked in `agents.json`, making them git-friendly and CI/CD-ready.

**Work with branches locally:**

```bash
# List branches for an agent
elevenlabs agents branches list --agent <agent_id>

# Pull a specific branch config
elevenlabs agents pull --agent <agent_id> --branch staging

# Push to a specific branch
elevenlabs agents push --agent <agent_id> --branch staging
```

**CI/CD pipeline (sync all branches):**

```bash
elevenlabs agents pull --all --all-branches --update --no-ui
# Make config changes...
elevenlabs agents push --no-ui
# Push auto-pushes main + all registered branch configs
```

Branch configs in `agents.json`:

```json
{
  "agents": [{
    "config": "agent_configs/My-Agent.json",
    "id": "agent_123",
    "branches": {
      "staging": {
        "config": "agent_configs/My-Agent.staging.json",
        "branch_id": "agtbrch_xxx",
        "version_id": "ver_xxx"
      }
    }
  }]
}
```

The `--branch` flag accepts both human-readable names (`staging`) and branch IDs (`agtbrch_xxx`).

## Workflow Examples

```bash
# List all agents
elevenlabs agents list

# Push all agents (main + branches)
elevenlabs agents push

# Pull agents (skips existing local agents)
elevenlabs agents pull

# Pull and update agents (overrides local with remote)
elevenlabs agents pull --update
```

## Troubleshooting

**Authentication Issues:**

```bash
# Check login status
elevenlabs auth whoami

# Login again
elevenlabs auth login

# Or use environment variable
export ELEVENLABS_API_KEY="your_api_key_here"
```

**Agent Not Found:**

- Check: `elevenlabs agents list`
- Verify: `elevenlabs agents status`

**Push Issues:**

- Preview: `elevenlabs agents push --dry-run`
- Check: `elevenlabs agents status`

**Reset Project:**

```bash
elevenlabs agents init --override
elevenlabs auth login
elevenlabs agents push
```

## Development

```bash
# Install dependencies
pnpm install

# Build
pnpm run build

# Test
pnpm test

# Lint
pnpm run lint
```

## Testing

### Unit Tests
```bash
npm test
```

### E2E Tests

**CRITICAL**: E2E tests require a **dedicated, empty test account**.

**DO NOT use your production account!** E2E tests will create, modify, and **delete agents** during testing. Any existing agents could be permanently lost.

**Setup:**

1. Create a new ElevenLabs account (separate from production)
2. Verify the account is completely empty (no deployed agents)
3. Generate an API key for this test account
4. Copy `.env.example` to `.env` and add the test account API key
5. Run: `npm run test:e2e`

**Quick safety check before running tests:**
```bash
npm run dev -- auth whoami --no-ui  # Verify you're using test account
npm run dev -- agents list --no-ui  # Should be empty or only test agents
```

## Security

The ElevenLabs CLI stores your API key securely with multiple fallback options:

- **Environment Variable**: `ELEVENLABS_API_KEY` takes highest priority for CI/CD
- **OS Keychain**: Uses native credential store (keytar) when available
- **Secure File**: Falls back to `~/.elevenlabs/api_key` with restricted permissions (600)

Configuration files are stored in `~/.elevenlabs/` with secure directory permissions (700 on Unix-like systems).

## Support

- Use `elevenlabs --help` or `elevenlabs <command> --help`
- Check GitHub issues
- Create new issue with problem details

cli

cli Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

cli

cli Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README