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

# CLI di ElevenLabs

## 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](https://github.com/elevenlabs/cli).

> **Non è necessaria alcuna installazione**
>
> Se lavori da Claude o da un altro client MCP, il [server MCP fornito](/docs/it/eleven-agents/operate/hosted-mcp) 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.

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

```bash
elevenlabs agents init
```

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

### Autenticati con ElevenLabs

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

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

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

### Carica sulla piattaforma ElevenLabs

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

**`Accesso`**

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

**`Disconnessione`**

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

## Gestione degli agenti

### Creazione di agenti

Crea agenti usando template predefiniti:

```bash
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:**

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

**`Elenca i template disponibili`**

```bash title="Elenca i template disponibili"
elevenlabs agents templates list
```

**`Mostra la configurazione del template`**

```bash title="Mostra la configurazione del template"
elevenlabs agents templates show <template>
```

### Sincronizzazione

Mantieni sincronizzate le configurazioni locali con la piattaforma ElevenLabs:

**`Carica tutti gli agenti`**

```bash title="Carica tutti gli agenti"
elevenlabs agents push
```

**`Anteprima delle modifiche (dry run)`**

```bash title="Anteprima delle modifiche (dry run)"
elevenlabs agents push --dry-run
```

### Stato e monitoraggio

**`Controlla lo stato dell'agente`**

```bash title="Controlla lo stato dell'agente"
elevenlabs agents status
```

### Importazione ed esportazione

**`Importa agenti esistenti`**

```bash title="Importa agenti esistenti"
elevenlabs agents pull
```

**`Importa un agente specifico`**

```bash title="Importa un agente specifico"
elevenlabs agents pull --agent <agent_id>
```

**`Aggiorna gli agenti`**

```bash title="Aggiorna gli agenti"
elevenlabs agents pull --update
```

**`Elenca tutti gli agenti`**

```bash title="Elenca tutti gli agenti"
elevenlabs agents list
```

> **Note**
>
> 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:

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

### Strumenti client

Integrazioni dirette lato client:

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

## Generazione del widget

Genera codice di incorporamento HTML per l'integrazione web:

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

Viene generato codice HTML come questo:

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

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

### Integrazione della pipeline CI/CD

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