ThunderPhone CLI

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:

npm install -g thunderphone
thunderphone --help

Accedi#

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.

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.

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.

Configurazione MCP#

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:

{
  "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#

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.