CLI de ThunderPhone

Inicia sesión, administra agentes de voz y llamadas, configura clientes MCP y crea la estructura inicial de proyectos desde la terminal.

La CLI requiere Node.js 18.18 o posterior. Ejecútala con npx o instálala globalmente:

npm install -g thunderphone
thunderphone --help

Iniciar sesión#

npx thunderphone login
thunderphone whoami --json

El inicio de sesión muestra un código de verificación, abre el navegador y espera la autorización. Usa --no-browser en una máquina sin interfaz gráfica y abre la URL mostrada en otro lugar. El inicio de sesión del dispositivo requiere que la API tenga habilitado el flujo de dispositivo OAuth. Una clave de API de organización en THUNDERPHONE_API_KEY también puede autenticar comandos y tiene prioridad sobre las credenciales de inicio de sesión almacenadas.

Las credenciales se almacenan por perfil en ~/.config/thunderphone/credentials.json con modo de archivo 0600. XDG_CONFIG_HOME y THUNDERPHONE_CONFIG_DIR reemplazan el directorio. Los tokens de acceso se renuevan automáticamente y los tokens de renovación rotativos se guardan de forma atómica. El inicio de sesión nunca muestra los tokens.

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

THUNDERPHONE_PROFILE establece el perfil predeterminado. El cierre de sesión elimina las credenciales locales; no revoca la autorización del servidor. La API predeterminada es https://api.thunderphone.com. Usa --api-base-url o THUNDERPHONE_API_BASE_URL para otra API. El token de un perfil no puede enviarse a una URL de API configurada diferente; inicia sesión en esa URL con un perfil independiente.

Comandos#

Cada comando acepta --json. Los datos correctos se envían a stdout; los errores se envían a stderr con un código de salida distinto de cero. Sin --json, la salida es una tabla compacta o una lista de campos. JSON conserva la estructura de respuesta de la API, con los campos de credenciales redactados. El servicio MCP reserva stdout para el protocolo MCP.

Las llamadas salientes requieren un número habilitado para llamadas salientes. THUNDERPHONE_FROM_NUMBER puede proporcionar --from. Los números VoIP del cliente siguen admitiendo llamadas salientes. Los números aprovisionados por ThunderPhone comienzan solo para llamadas entrantes; un administrador de la organización puede solicitar llamadas salientes desde la página Números telefónicos, donde cada solicitud se revisa manualmente. --wait usa de forma predeterminada un tiempo de espera de una hora; configura --timeout SECONDS para cambiarlo. Un tiempo de espera deja de esperar sin finalizar la llamada.

Los SMS también requieren un número compatible con SMS en tu cuenta conectada de Twilio o Telnyx. Nunca se envían desde un número propiedad de ThunderPhone. Reutiliza una clave de idempotencia solo cuando reintentes exactamente el mismo remitente, destinatario y cuerpo.

Las importaciones admiten vapi, retell, elevenlabs y bland. El segundo argumento es una ruta a una exportación JSON de proveedor, no un ID remoto de proveedor. La API prepara una asignación de forma asíncrona; inspeciónala con imports get UUID y confirma solo cuando esté lista y hayas revisado los campos asignados y las advertencias. Consulta importaciones de agentes.

Configuración de 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 y windsurf. El alcance del proyecto es el predeterminado. Desktop y Windsurf requieren alcance de usuario. Omite --client para detectar un único cliente del proyecto; una detección ambigua solicita interacción o falla con instrucciones en una sesión no interactiva. La configuración muestra el archivo que escribió y conserva servidores no relacionados. El JSON existente debe ser JSON estricto válido; los valores TOML de Codex se conservan, pero los comentarios pueden reformatearse.

La configuración prefiere HTTP remoto directo. Con --api-key-env, escribe una referencia a la variable, nunca la clave. Sin esa opción, HTTP directo depende del soporte OAuth del cliente; no usa el archivo de credenciales de la CLI. Para reutilizar las credenciales de thunderphone login en cualquier cliente compatible con stdio, usa:

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

El wrapper verifica THUNDERPHONE_API_KEY, luego el perfil actual de la CLI (actualizándolo cuando es necesario) y después delega OAuth a mcp-remote. THUNDERPHONE_MCP_URL anula el endpoint. No emite telemetría. La configuración independiente también está disponible mediante npx -y @thunderphone/mcp setup --client cursor o thunderphone-mcp setup después de instalar @thunderphone/mcp globalmente.

Crea un proyecto#

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

Las plantillas son node y python; los tipos de agente son receptionist, outbound y custom. El agente predeterminado es una recepcionista dental en inglés/español con datos de demostración explícitos. Los proyectos incluyen agent.json, scripts de despliegue, configuraciones MCP para Claude Code, Cursor y VS Code, instrucciones del agente, .env.example y un README. El scaffolding funciona sin conexión y se niega a sobrescribir un directorio que no esté vacío.

Edita los datos del negocio antes del despliegue. Exporta la clave de API, el número conectado de quienes llaman y el destinatario de prueba como se documenta en el README generado. npm run deploy o python deploy.py crea o actualiza el agente, despliega su borrador y realiza una llamada de prueba facturable. Los scripts usan autenticación mediante clave de API; la CLI y el wrapper MCP stdio también admiten inicio de sesión en el dispositivo. Los scripts de Python requieren Python 3.9 o una versión posterior.