CLI do ThunderPhone

Faça login, gerencie agentes de voz e chamadas, configure clientes MCP e crie a estrutura inicial de projetos pelo terminal.

A CLI requer o Node.js 18.18 ou posterior. Execute-a com npx ou instale-a globalmente:

npm install -g thunderphone
thunderphone --help

Fazer login#

npx thunderphone login
thunderphone whoami --json

O login exibe um código de verificação, abre o navegador e aguarda a autorização. Use --no-browser em uma máquina sem interface gráfica e abra a URL exibida em outro local. O login de dispositivo requer a disponibilização do fluxo de dispositivo OAuth da API. Uma chave de API da organização em THUNDERPHONE_API_KEY também pode autenticar comandos e tem precedência sobre as credenciais de login armazenadas.

As credenciais são armazenadas por perfil em ~/.config/thunderphone/credentials.json com permissão de arquivo 0600. XDG_CONFIG_HOME e THUNDERPHONE_CONFIG_DIR substituem o diretório. Os tokens de acesso são renovados automaticamente, e os tokens de atualização rotativos são salvos atomicamente. Os tokens nunca são exibidos pelo login.

thunderphone login --profile work
thunderphone agents list --profile work --json
thunderphone logout --profile work

THUNDERPHONE_PROFILE define o perfil padrão. O logout remove as credenciais locais; ele não revoga a concessão no servidor. A API padrão é https://api.thunderphone.com. Use --api-base-url ou THUNDERPHONE_API_BASE_URL para outra API. O token de um perfil não pode ser enviado para uma URL de API configurada diferente; faça login nessa URL com um perfil separado.

Comandos#

Todos os comandos aceitam --json. Os dados bem-sucedidos vão para stdout; os erros vão para stderr com um código de saída diferente de zero. Sem --json, a saída é uma tabela compacta ou uma lista de campos. O JSON mantém a estrutura de resposta da API, com campos de credenciais ocultados. O serviço MCP reserva stdout para o protocolo MCP.

Chamadas de saída exigem um número habilitado para saída. THUNDERPHONE_FROM_NUMBER pode fornecer --from. Números VoIP do cliente continuam a oferecer suporte a chamadas de saída. Números provisionados pelo ThunderPhone começam apenas para entrada; um administrador da organização pode solicitar chamadas de saída na página Números de telefone, onde cada solicitação é revisada manualmente. --wait usa por padrão um tempo limite de uma hora; defina --timeout SECONDS para alterá-lo. Um tempo limite interrompe a espera sem encerrar a chamada.

O SMS também exige um número compatível com SMS na sua conta conectada do Twilio ou Telnyx. Ele nunca envia de um número pertencente ao ThunderPhone. Reutilize uma chave de idempotência somente ao tentar novamente com exatamente o mesmo remetente, destinatário e corpo.

As importações oferecem suporte a vapi, retell, elevenlabs e bland. O segundo argumento é um caminho para uma exportação JSON do fornecedor, não um ID remoto do fornecedor. A API prepara um mapeamento de forma assíncrona; inspecione-o com imports get UUID e confirme somente depois que estiver pronto e você tiver revisado os campos mapeados e os avisos. Consulte importações de agentes.

Configuração do 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

Clientes: claude-code, codex, cursor, vscode, gemini, claude-desktop e windsurf. O escopo do projeto é o padrão. Desktop e Windsurf exigem escopo de usuário. Omita --client para detectar um único cliente no projeto; uma detecção ambígua solicita interação ou falha com instruções em uma sessão não interativa. A configuração exibe o arquivo que gravou e preserva servidores não relacionados. O JSON existente deve ser JSON estrito válido; os valores TOML do Codex são preservados, mas os comentários podem ser reformatados.

A configuração prefere HTTP remoto direto. Com --api-key-env, ela grava uma referência à variável, nunca a chave. Sem essa opção, o HTTP direto depende do suporte a OAuth do cliente; ele não usa o arquivo de credenciais da CLI. Para reutilizar as credenciais de thunderphone login em qualquer cliente compatível com stdio, use:

{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": ["-y", "@thunderphone/mcp"]
    }
  }
}

O wrapper verifica THUNDERPHONE_API_KEY, depois o perfil atual da CLI (atualizando-o quando necessário) e, em seguida, delega o OAuth a mcp-remote. THUNDERPHONE_MCP_URL substitui o endpoint. Ele não envia telemetria. A configuração independente também está disponível por meio de npx -y @thunderphone/mcp setup --client cursor ou thunderphone-mcp setup após instalar @thunderphone/mcp globalmente.

Criar um projeto#

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

Os modelos são node e python; os tipos de agente são receptionist, outbound e custom. O agente padrão é uma recepcionista odontológica em inglês/espanhol com fatos de demonstração explícitos. Os projetos incluem agent.json, scripts de implantação, configurações MCP para Claude Code, Cursor e VS Code, instruções do agente, .env.example e um README. A criação do esqueleto funciona offline e se recusa a sobrescrever um diretório não vazio.

Edite os dados da empresa antes da implantação. Exporte a chave de API, o número conectado de quem liga e o destinatário de teste, conforme documentado no README gerado. npm run deploy ou python deploy.py cria ou atualiza o agente, implanta seu rascunho e realiza uma chamada de teste faturável. Os scripts usam autenticação por chave de API; a CLI e o wrapper MCP stdio também oferecem suporte a login por dispositivo. Os scripts Python exigem Python 3.9 ou posterior.