Conversational AI CLI

Overview

The ElevenLabs ConvAI CLI transforms how you build and deploy conversational AI agents by treating them as code. Instead of manually configuring agents through web interfaces, you define them in version-controlled configuration files and deploy them like any other application.

The CLI also provides a local scratch pad that coding agents like claude code can use to reason about your voice agents. Whether you’re auto-generating customer support bots from your existing documentation, creating personalized sales agents for each client, or building docs agents that stay synchronized with your codebase, the CLI makes it effortless.

What you can build

• Instant docs agents: Generate agents from your API documentation that are always up-to-date with your latest changes
• Site-aware assistants: Parse your Vercel app routes and components to create agents that understand your application structure
• Integration-ready bots: Connect to your existing APIs, databases, and tools through webhook and client-side integrations

Key features

• Agents as Code: Version control your AI agents alongside your application code—never lose track of changes or accidentally overwrite production configurations
• Multi-environment Support: Deploy the same agent logic across dev, staging, and production with environment-specific configurations and API keys
• Secure Authentication: Production-ready security with OS keychain integration and environment variable support for CI/CD pipelines
• Tool Management: Connect to any API, database, or service through webhook and client-side tool integrations with built-in authentication

Installation

The CLI requires Node.js version 16.0.0 or higher.

$
npm install -g @elevenlabs/convai-cli

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

Quick start

$
convai init

$
convai login

$
convai add agent "My Assistant" --template assistant

$
convai sync

Project structure

The CLI creates a structured project directory:

your_project/
├── agents.json              # Central agent configuration registry
├── tools.json               # Tool definitions registry
├── agent_configs/           # Environment-specific agent configs
│   ├── prod/                # Production environment configs
│   ├── dev/                 # Development environment configs
│   └── staging/             # Staging environment configs
├── tool_configs/            # Tool configuration files
└── convai.lock             # Lock file with agent IDs and hashes

Authentication

The CLI uses a multi-layered authentication system for secure API key management:

Authentication commands

$
convai login

Agent management

Creating agents

Create agents using pre-built templates:

$
convai add agent "Agent Name" [options]

Options:

• --template <type>: Choose from available templates (default: default)
• --env <env>: Target environment (default: dev)
• --skip-upload: Create locally without uploading to platform

Example:

$
convai add agent "Customer Support Bot" --template customer-service --env prod

Templates

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

Template commands

$
convai templates list

Synchronization

Keep your local configurations synchronized with the ElevenLabs platform:

$
convai sync

Status and monitoring

$
convai status

Import and export

$
convai fetch --env prod

Tool management

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

Webhook tools

HTTP API integrations with authentication and timeout configuration:

$
convai add webhook-tool "API Integration" --config-path ./tool-config.json

Client tools

Direct client-side integrations:

$
convai add client-tool "Client Function" --config-path ./client-config.json

Widget generation

Generate HTML embed code for web integration:

$
convai widget "Agent Name" --env prod

This outputs HTML code like:

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

Configuration files

Agent configuration structure

Each agent configuration includes:

1
{
2
  "name": "Agent Name",
3
  "conversation_config": {
4
    "agent": {
5
      "prompt": "You are a helpful assistant...",
6
      "llm": {
7
        "model": "eleven-multilingual-v1",
8
        "temperature": 0.3
9
      },
10
      "language": "en",
11
      "tools": []
12
    },
13
    "tts": {
14
      "model": "eleven-multilingual-v1",
15
      "voice_id": "pNInz6obpgDQGcFmaJgB",
16
      "audio_format": {
17
        "format": "pcm",
18
        "sample_rate": 44100
19
      }
20
    },
21
    "asr": {
22
      "model": "nova-2-general",
23
      "language": "auto"
24
    },
25
    "conversation": {
26
      "max_duration_seconds": 1800,
27
      "text_only": false,
28
      "client_events": []
29
    }
30
  },
31
  "platform_settings": {
32
    "widget": {
33
      "conversation_starters": [],
34
      "branding": {}
35
    }
36
  },
37
  "tags": ["environment:dev"]
38
}

Environment management

The CLI supports multiple environments with separate configurations:

$
convai add agent "Test Bot" --env dev
>
convai sync --env dev

CI/CD pipeline integration

$
# In your GitHub Actions workflow
>
- name: Deploy ConvAI agents
>
  run: |
>
    npm install -g @elevenlabs/convai-cli
>
    export ELEVENLABS_API_KEY=${{ secrets.ELEVENLABS_API_KEY }}
>
    convai sync --env prod --dry-run  # Preview changes
>
    convai sync --env prod            # Deploy
>
    convai status --env prod          # Verify deployment