CLI di ElevenLabs

Gestisci i tuoi agenti vocali come codice dalla riga di comando.

Panoramica

La CLI di ElevenLabs ti consente di accedere ai tuoi agenti ElevenLabs dal terminale, offrendo nuovi modi per gestirli:

Archivia gli agenti come codice nel tuo sistema di controllo versione
Configura l’integrazione CI/CD per distribuire automaticamente i tuoi agenti
Consenti al tuo coding agent di accedere e gestire i tuoi agenti vocali

Preferisci passare subito al codice?

Trova il codice sorgente completo e contribuisci su GitHub.

Non è necessaria alcuna installazione

Se lavori da Claude o da un altro client MCP, il server MCP fornito offre strumenti di gestione degli agenti senza installazione locale. Usa la CLI quando vuoi inserire gli agenti nel controllo versione; usa il server MCP fornito per la gestione conversazionale.

Installazione

Homebrew (macOS) e Scoop (Windows) sono i metodi di installazione consigliati e forniscono un binario standalone.

brew install elevenlabs/tap/elevenlabs

Lavori con un assistente di coding IA? Esegui elevenlabs generate-skills nel tuo progetto per creare un file SKILL.md per ogni gruppo di comandi in skills/, così il tuo assistente conosce tutte le funzionalità della CLI senza che tu debba incollare la documentazione. Usa --output-dir per inserirli altrove. Il comando legge la definizione API integrata della CLI, quindi non richiede una chiave API e funziona offline — inoltre rimane allineato alla versione della CLI che hai installato.

Dopo l’installazione, il comando elevenlabs sarà disponibile globalmente nel tuo terminale.

Guida rapida

Inizializza un nuovo progetto

elevenlabs agents init

Questo crea la struttura del progetto con directory di configurazione e file di registro.

Autenticati con ElevenLabs

elevenlabs auth login

Si aprirà una finestra del browser per autenticarti tramite OAuth. La CLI verificherà le credenziali e le memorizzerà in modo sicuro.

Crea il tuo primo agente

elevenlabs agents add "My Assistant" --template assistant

Questo crea una nuova configurazione dell’agente usando il template assistant.

Carica sulla piattaforma ElevenLabs

elevenlabs agents push

Questo carica la configurazione dell’agente locale sulla piattaforma ElevenLabs.

Struttura del progetto

La CLI crea una directory di progetto strutturata:

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

Autenticazione

elevenlabs auth login memorizza le credenziali nel portachiavi del tuo sistema operativo: Keychain su macOS, Credential Manager su Windows e Secret Service su Linux. Quando non è disponibile alcun portachiavi, la CLI usa come alternativa ~/.config/elevenlabs/auth-keyring.json con autorizzazioni 0600. Esegui elevenlabs auth status per vedere quale origine è in uso e elevenlabs auth logout per rimuovere la voce memorizzata.

Per CI, imposta ELEVENLABS_API_KEY nell’ambiente o in un file .env invece di effettuare l’accesso.

Comandi di autenticazione

elevenlabs auth login

Gestione degli agenti

Creazione di agenti

Crea agenti usando template predefiniti:

elevenlabs agents add "Agent Name" [options]

Opzioni:

--template <type>: Scegli tra i template disponibili (predefinito: default)
--skip-upload: Crea localmente senza caricare sulla piattaforma

Esempio:

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

Template

La CLI offre sei template predefiniti per casi d’uso comuni:

default

Configurazione completa con tutti i campi disponibili, valori predefiniti sensati, supporto completo per voce/testo, personalizzazione del widget e criteri di valutazione.

minimal

Solo i campi essenziali, inclusi prompt di base, lingua, TTS e impostazioni della conversazione.

voice-only

Ottimizzato per le interazioni vocali, con input di testo disabilitato e impostazioni vocali avanzate.

text-only

Conversazioni incentrate sul testo con funzionalità vocali disabilitate.

customer-service

Prompt professionali ed empatici, bassa temperatura (0.1), durata di 30 minuti e criteri di valutazione.

assistant

Assistente IA generico con creatività bilanciata (temperatura 0.3) e supporto versatile per voce/testo.

Comandi dei template

elevenlabs agents templates list

Sincronizzazione

Mantieni sincronizzate le configurazioni locali con la piattaforma ElevenLabs:

elevenlabs agents push

Stato e monitoraggio

Controlla lo stato dell'agente

elevenlabs agents status

Importazione ed esportazione

elevenlabs agents pull

Per impostazione predefinita, elevenlabs agents pull ignora gli agenti già presenti localmente. Usa il flag --update per sostituire le configurazioni locali con modifiche remote apportate nel browser o tramite l’API.

Gestione degli strumenti

La CLI supporta due tipi di strumenti per estendere le funzionalità degli agenti:

Strumenti webhook

Integrazioni HTTP API con configurazione di autenticazione e timeout:

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

Strumenti client

Integrazioni dirette lato client:

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

Genera codice di incorporamento HTML per l’integrazione web:

elevenlabs agents widget embed <agent_id>

Viene generato codice HTML come questo:

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

File di configurazione

Struttura della configurazione dell’agente

Ogni configurazione dell’agente include:

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

Integrazione della pipeline 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