CLI da ElevenLabs | ElevenLabs Documentation

Visão geral

A CLI da ElevenLabs permite acessar seus agentes da ElevenLabs pelo terminal, oferecendo novas formas de gerenciá-los:

Armazene agentes como código no seu sistema de controle de versão
Configure a integração de CI/CD para implantar seus agentes automaticamente
Permita que seu agente de programação acesse e gerencie seus agentes de voz

Prefere ir direto para o código?

Encontre o código-fonte completo e contribua no GitHub.

Não é necessário instalar

Se você trabalha pelo Claude ou outro cliente MCP, o servidor MCP hospedado oferece ferramentas de gerenciamento de agentes sem instalação local. Use a CLI quando quiser manter agentes no controle de versão; use o servidor MCP hospedado para gerenciamento conversacional.

Instalação

Homebrew (macOS) e Scoop (Windows) são os métodos de instalação recomendados e fornecem um binário independente.

brew install elevenlabs/tap/elevenlabs

Está trabalhando com um assistente de programação com IA? Execute elevenlabs generate-skills no seu projeto para criar um SKILL.md para cada grupo de comandos em skills/, para que seu assistente conheça toda a superfície da CLI sem que você precise colar a documentação. Use --output-dir para colocá-los em outro lugar. Isso lê a própria definição de API incorporada da CLI, portanto não precisa de chave de API e funciona off-line — além de acompanhar a versão da CLI que você tiver instalado.

Após a instalação, o comando elevenlabs estará disponível globalmente no seu terminal.

Início rápido

Inicialize um novo projeto

elevenlabs agents init

Isso cria a estrutura do projeto com diretórios de configuração e arquivos de registro.

Autentique-se na ElevenLabs

elevenlabs auth login

Isso abrirá uma janela do navegador para autenticação via OAuth. A CLI verificará as credenciais e as armazenará com segurança.

Crie seu primeiro agente

elevenlabs agents add "My Assistant" --template assistant

Isso cria uma nova configuração de agente usando o modelo de assistente.

Envie para a plataforma da ElevenLabs

elevenlabs agents push

Isso envia a configuração local do seu agente para a plataforma da ElevenLabs.

Estrutura do projeto

A CLI cria um diretório de projeto estruturado:

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

Autenticação

elevenlabs auth login armazena credenciais no chaveiro do seu sistema operacional — Keychain no macOS, Gerenciador de Credenciais no Windows e Secret Service no Linux. Quando não há chaveiro disponível, a CLI usa como alternativa ~/.config/elevenlabs/auth-keyring.json com permissões 0600. Execute elevenlabs auth status para ver qual fonte está em uso e elevenlabs auth logout para remover a entrada armazenada.

Para CI, defina ELEVENLABS_API_KEY no ambiente ou em um arquivo .env, em vez de fazer login.

Comandos de autenticação

elevenlabs auth login

Gerenciamento de agentes

Criando agentes

Crie agentes usando modelos prontos:

elevenlabs agents add "Agent Name" [options]

Opções:

--template <type>: escolha entre os modelos disponíveis (padrão: default)
--skip-upload: crie localmente sem enviar para a plataforma

Exemplo:

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

Modelos

A CLI oferece seis modelos prontos para casos de uso comuns:

default

Configuração completa com todos os campos disponíveis, padrões adequados, suporte completo a voz/texto, personalização de widget e critérios de avaliação.

minimal

Apenas campos essenciais, incluindo prompt básico, idioma, TTS e configurações de conversa.

voice-only

Otimizado para interações por voz, com entrada de texto desativada e configurações avançadas de voz.

text-only

Conversas voltadas a texto, com recursos de voz desativados.

customer-service

Prompts profissionais e empáticos, baixa temperatura (0.1), duração de 30 minutos e critérios de avaliação.

assistant

Assistente de IA de uso geral, com criatividade equilibrada (temperatura 0.3) e suporte versátil a voz/texto.

Comandos de modelos

elevenlabs agents templates list

Sincronização

Mantenha suas configurações locais sincronizadas com a plataforma da ElevenLabs:

elevenlabs agents push

Status e monitoramento

Verificar status do agente

elevenlabs agents status

Importação e exportação

elevenlabs agents pull

Por padrão, elevenlabs agents pull ignora agentes que já existem localmente. Use a flag --update para substituir configurações locais por alterações remotas feitas no navegador ou pela API.

Gerenciamento de ferramentas

A CLI oferece suporte a dois tipos de ferramentas para ampliar os recursos dos agentes:

Ferramentas de webhook

Integrações de API HTTP com configuração de autenticação e tempo limite:

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

Ferramentas de cliente

Integrações diretas no lado do cliente:

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

Gere código de incorporação HTML para integração na web:

elevenlabs agents widget embed <agent_id>

Isso gera código HTML como:

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

Arquivos de configuração

Estrutura da configuração do agente

Cada configuração de agente inclui:

{
  "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": []
}

Integração com pipeline de CI/CD

# 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