---
title: "CLI de ThunderPhone"
description: "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:

```bash
npm install -g thunderphone
thunderphone --help
```

## Iniciar sesión

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

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

| Comando | Propósito |
| --- | --- |
| `login [--no-browser] [--scope "scopes"]` | Autorizar mediante un código de dispositivo |
| `logout`, `whoami` | Eliminar credenciales locales; listar organizaciones accesibles |
| `agents list`, `agents get ID` | Leer agentes |
| `agents create --file agent.json` | Crear un agente |
| `agents update ID --file agent.json` | Guardar un borrador de agente |
| `agents deploy ID`, `agents delete ID` | Implementar el borrador; eliminar un agente |
| `numbers list` | Leer números telefónicos |
| `numbers provision --country US --area-code 415` | Aprovisionar un número entrante de EE. UU. |
| `numbers assign NUMBER_ID --agent ID` | Asignar un agente entrante |
| `sms send TO --from FROM --body TEXT --idempotency-key KEY` | Enviar SMS mediante un número de operador conectado por el cliente con reintento seguro |
| `sms list [--limit N]`, `sms get UUID` | Listar o inspeccionar registros de SMS |
| `call TO --agent ID --from FROM [--wait]` | Realizar una llamada saliente; esperar opcionalmente su transcripción |
| `calls list [--limit N] [--agent ID]` | Listar llamadas (límite de 1 a 200) |
| `calls get ID`, `calls transcript ID` | Leer una llamada o su transcripción |
| `test run AGENT_ID [--scenario ID] --consent-to-charge` | Ejecutar escenarios guardados facturables mediante el canal web |
| `test status RUN_ID [--agent ID]` | Inspeccionar un lote, con detalles del escenario cuando se proporciona un agente |
| `import VENDOR export.json` | Preparar una importación de JSON de proveedor para revisión |
| `imports get UUID`, `imports commit UUID` | Inspeccionar una importación; confirmar los agentes seleccionados después de la revisión |
| `mcp setup`, `mcp serve` | Configurar un cliente; iniciar el puente stdio |
| `init [directory]` | Crear la estructura inicial de un proyecto |

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](/es/guides/import-agents).

## Configuración de 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
```

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:

```json
{
  "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

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

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.