ryvo es la línea de comandos oficial de la API de Ryvo. Cada comando es una capa fina y tipada sobre un endpoint público, así que puede hacer exactamente lo que tu llave permite y nada más.
Instalar
Node.js 20 o superior.Entrar
La CLI usa una llave de API normal. No puede crear llaves: la API no lo permite a propósito, para que una llave filtrada nunca pueda fabricar otra. Crea la llave en el portal, en Configuración → API keys (app.ryvo.so/configuracion/api-keys), con los mínimos scopes que necesites, y luego:ryvo login comprueba la llave con GET /v1/me antes de guardarla. Se guarda en ~/.config/ryvo/config.json (%APPDATA%\ryvo\config.json en Windows) con permisos 0600 donde el sistema los respeta. Nunca se imprime entera: sólo su prefijo (ryvo_live_abc123...).
En CI, en contenedores o con un gestor de secretos, sáltate el archivo y pon la llave en el entorno. RYVO_API_KEY siempre gana sobre la llave guardada:
ryvo logout borra la llave guardada en esta máquina. No la revoca; eso se hace en el portal.
Comandos
ryvo <grupo> --help lista las opciones de cada comando. Algunos ejemplos:
Comandos que gastan créditos
ryvo calls create hace una llamada telefónica real y ryvo campaigns create lanza una llamada por destinatario. Los dos:
- piden confirmación antes de mandar nada. En scripts pasa
--yes; sin terminal y sin--yesse niegan en vez de adivinar. - siempre mandan una
Idempotency-Key(un uuid nuevo salvo que pases--idempotency-key) y la imprimen, para que un reintento tras un timeout la reutilice y nunca marque dos veces. Mira Idempotencia.
--recipients acepta un arreglo JSON de destinatarios o un archivo de texto o CSV con un número E.164 por línea. La protección de verdad es el tope de créditos de la llave, que se pone en el portal.
Paginación
Toda lista acepta--limit (1 a 100) y --cursor. --all sigue next_cursor hasta la última página, de 100 en 100. Sin --all, la CLI imprime el siguiente cursor cuando hay más.
La salida de emergencia: ryvo api
Como gh api: cualquier método y ruta, con tu llave, los reintentos y los códigos de salida, imprimiendo el JSON tal cual.
v1/models sin la barra inicial (Git Bash reescribe las rutas que empiezan con /).
Salida JSON y códigos de salida
Por omisión salen tablas para leer, que pueden cambiar entre versiones. Para scripts, añade--json: imprime la respuesta de la API exactamente como la documenta la referencia. Con --json, los errores salen por stderr como { "error", "message", "request_id", "exit_code" }.
Todo error imprime el request_id de la API: cítalo cuando nos escribas. Las respuestas 429 y 503 se reintentan hasta 3 veces, respetando Retry-After (o X-RateLimit-Reset), y nunca esperando más de un minuto. Mira Límites de uso.
El código de salida sale del error de la API, para que un script pueda ramificar sin leer texto:
Un código que la CLI todavía no conoce cae por su status HTTP (por ejemplo, cualquier
402 es 8).
Conectar el servidor MCP
ryvo mcp install añade el servidor MCP de Ryvo (https://mcp.ryvo.so) a tu cliente de IA, para que el asistente pueda leer tus agentes, llamadas y campañas.
--scope project para escribir el archivo del proyecto (.mcp.json, .cursor/mcp.json o .vscode/mcp.json), --config <ruta> para elegir el archivo y --dry-run para ver el resultado sin escribir.
- Mezcla: los demás servidores y ajustes del archivo se conservan, y antes se escribe un respaldo con fecha (
<archivo>.bak-20260929T123456Z). Un archivo con comentarios no se toca y se imprime la entrada para que la pegues. - La llave nunca se escribe en el archivo. Claude Code, Cursor y Windsurf la leen de la variable de entorno
RYVO_API_KEYdel cliente; VS Code la pide una vez y la guarda cifrada.