--- title: "ThunderPhone CLI" description: "Accedi, gestisci agenti vocali e chiamate, configura client MCP e crea lo scheletro di progetti dal terminale." --- La CLI richiede Node.js 18.18 o versione successiva. Eseguila con `npx` oppure installala globalmente: ```bash npm install -g thunderphone thunderphone --help ``` ## Accedi ```bash npx thunderphone login thunderphone whoami --json ``` Il login stampa un codice di verifica, apre il browser e attende l'autorizzazione. Usa `--no-browser` su una macchina headless e apri altrove l'URL stampato. Il login del dispositivo richiede l'abilitazione del flusso OAuth per dispositivi dell'API. Una chiave API dell'organizzazione in `THUNDERPHONE_API_KEY` può inoltre autenticare i comandi e ha precedenza sulle credenziali di login archiviate. Le credenziali vengono archiviate per profilo in `~/.config/thunderphone/credentials.json` con modalità file `0600`. `XDG_CONFIG_HOME` e `THUNDERPHONE_CONFIG_DIR` sovrascrivono la directory. I token di accesso vengono aggiornati automaticamente e i token di aggiornamento a rotazione vengono salvati atomicamente. Il login non stampa mai i token. ```bash thunderphone login --profile work thunderphone agents list --profile work --json thunderphone logout --profile work ``` `THUNDERPHONE_PROFILE` imposta il profilo predefinito. Il logout rimuove le credenziali locali; non revoca l'autorizzazione sul server. L'API predefinita è `https://api.thunderphone.com`. Usa `--api-base-url` o `THUNDERPHONE_API_BASE_URL` per un'altra API. Il token di un profilo non può essere inviato a un URL API configurato diverso; accedi a quell'URL con un profilo separato. ## Comandi Ogni comando accetta `--json`. I dati restituiti correttamente vengono inviati a stdout; gli errori a stderr con un codice di uscita diverso da zero. Senza `--json`, l'output è una tabella compatta o un elenco di campi. JSON conserva la struttura della risposta API, con i campi delle credenziali oscurati. Il servizio MCP riserva stdout al protocollo MCP. | Comando | Scopo | | --- | --- | | `login [--no-browser] [--scope "scopes"]` | Autorizza tramite un codice dispositivo | | `logout`, `whoami` | Rimuovi le credenziali locali; elenca le organizzazioni accessibili | | `agents list`, `agents get ID` | Leggi gli agenti | | `agents create --file agent.json` | Crea un agente | | `agents update ID --file agent.json` | Salva una bozza dell'agente | | `agents deploy ID`, `agents delete ID` | Distribuisci la bozza; elimina un agente | | `numbers list` | Leggi i numeri di telefono | | `numbers provision --country US --area-code 415` | Attiva un numero statunitense per le chiamate in entrata | | `numbers assign NUMBER_ID --agent ID` | Assegna un agente per le chiamate in entrata | | `sms send TO --from FROM --body TEXT --idempotency-key KEY` | Invia SMS tramite un numero dell'operatore connesso dal cliente con ripetizione sicura | | `sms list [--limit N]`, `sms get UUID` | Elenca o ispeziona i record SMS | | `call TO --agent ID --from FROM [--wait]` | Effettua una chiamata in uscita; facoltativamente attendi la relativa trascrizione | | `calls list [--limit N] [--agent ID]` | Elenca le chiamate (limite 1–200) | | `calls get ID`, `calls transcript ID` | Leggi una chiamata o la relativa trascrizione | | `test run AGENT_ID [--scenario ID] --consent-to-charge` | Esegui scenari salvati fatturabili usando il canale web | | `test status RUN_ID [--agent ID]` | Ispeziona un batch, con dettagli dello scenario quando viene fornito un agente | | `import VENDOR export.json` | Prepara un'importazione JSON di un fornitore per la revisione | | `imports get UUID`, `imports commit UUID` | Ispeziona un'importazione; conferma gli agenti selezionati dopo la revisione | | `mcp setup`, `mcp serve` | Configura un client; avvia il bridge stdio | | `init [directory]` | Crea la struttura di un progetto | Le chiamate in uscita richiedono un numero abilitato alle chiamate in uscita. `THUNDERPHONE_FROM_NUMBER` può fornire `--from`. I numeri VoIP del cliente continuano a supportare le chiamate in uscita. I numeri attivati da ThunderPhone iniziano come solo in entrata; un amministratore dell'organizzazione può richiedere le chiamate in uscita dalla pagina Phone Numbers, dove ogni richiesta viene esaminata manualmente. `--wait` usa per impostazione predefinita un timeout di un'ora; imposta `--timeout SECONDS` per modificarlo. Un timeout interrompe l'attesa senza terminare la chiamata. Gli SMS richiedono inoltre un numero abilitato agli SMS nel tuo account Twilio o Telnyx connesso. Non vengono mai inviati da un numero di proprietà di ThunderPhone. Riutilizza una chiave di idempotenza solo quando ritenti con lo stesso identico mittente, destinatario e corpo. Le importazioni supportano `vapi`, `retell`, `elevenlabs` e `bland`. Il secondo argomento è un percorso a un'esportazione JSON del fornitore, non un ID remoto del fornitore. L'API prepara una mappatura in modo asincrono; ispezionala con `imports get UUID` e confermala solo dopo che è pronta e dopo aver esaminato i campi mappati e gli avvisi. Consulta [importazioni di agenti](/it/guides/import-agents). ## Configurazione MCP ```bash thunderphone mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY thunderphone mcp setup --client codex --scope user --api-key-env THUNDERPHONE_API_KEY thunderphone mcp setup --client claude-desktop --scope user ``` Client: `claude-code`, `codex`, `cursor`, `vscode`, `gemini`, `claude-desktop` e `windsurf`. L'ambito del progetto è quello predefinito. Desktop e Windsurf richiedono l'ambito utente. Ometti `--client` per rilevare un singolo client dal progetto; il rilevamento ambiguo richiede un'interazione oppure non riesce con istruzioni in una sessione non interattiva. La configurazione stampa il file che ha scritto e conserva i server non correlati. Il JSON esistente deve essere JSON rigoroso valido; i valori TOML di Codex vengono conservati, ma i commenti potrebbero essere riformattati. La configurazione preferisce HTTP remoto diretto. Con `--api-key-env`, scrive un riferimento a una variabile, mai la chiave. Senza questa opzione, HTTP diretto si basa sul supporto OAuth del client; non usa il file delle credenziali della CLI. Per riutilizzare le credenziali di `thunderphone login` in qualsiasi client compatibile con stdio, usa: ```json { "mcpServers": { "thunderphone": { "command": "npx", "args": ["-y", "@thunderphone/mcp"] } } } ``` Il wrapper controlla `THUNDERPHONE_API_KEY`, poi il profilo CLI corrente (aggiornandolo quando necessario), quindi delega OAuth a `mcp-remote`. `THUNDERPHONE_MCP_URL` sovrascrive l'endpoint. Non invia telemetria. La configurazione autonoma è disponibile anche tramite `npx -y @thunderphone/mcp setup --client cursor` o `thunderphone-mcp setup` dopo aver installato globalmente `@thunderphone/mcp`. ## Crea un progetto ```bash npx create-thunderphone-agent my-receptionist npx create-thunderphone-agent my-outbound --template python --agent-type outbound # Equivalent: thunderphone init my-receptionist --template node --agent-type receptionist ``` I modelli sono `node` e `python`; i tipi di agente sono `receptionist`, `outbound` e `custom`. L'agente predefinito è un receptionist dentale in inglese/spagnolo con fatti dimostrativi espliciti. I progetti includono `agent.json`, script di distribuzione, configurazioni MCP per Claude Code, Cursor e VS Code, istruzioni per l'agente, `.env.example` e un README. La generazione dello scheletro funziona offline e rifiuta di sovrascrivere una directory non vuota. Modifica i dati aziendali prima della distribuzione. Esporta la chiave API, il numero del chiamante connesso e il destinatario del test come documentato nel README generato. `npm run deploy` o `python deploy.py` crea o aggiorna l'agente, distribuisce la sua bozza ed effettua una chiamata di test fatturabile. Gli script usano l'autenticazione con chiave API; la CLI e il wrapper MCP stdio supportano anche l'accesso da dispositivo. Gli script Python richiedono Python 3.9 o versione successiva.