1
Ejecutar la CLI
Usa npx sin instalación global. El paquete publicado requiere Node.js 20 o posterior.
node --version
npx -y @poyoapi/cli helpPoYo CLIpaquete npm disponible
Descubre y ejecuta modelos de PoYo desde tu terminal.
Busca en el catálogo en tiempo real y consulta los Schema sin API Key. Autentícate cuando vayas a transmitir chat, enviar una generación o recuperar una tarea mediante task_id.
$npx -y @poyoapi/cli helpEmpieza a usar PoYo CLI en tres pasos
Ejecuta la CLI y elige un modelo con models y describe. Añade una API Key solo para ejecutar un modelo o consultar los datos de la cuenta.
2
Elegir un modelo
Este ejemplo encuentra el modelo gpt-image-2 disponible actualmente y luego consulta su Schema de entrada en tiempo real y su precio público. Ninguno de los dos comandos requiere una clave de API.
npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
npx -y @poyoapi/cli describe gpt-image-23
Autenticar y ejecutar
Crea una API Key y completa en orden los tres comandos siguientes. Consulta el precio con describe antes de la ejecución de pago; las generaciones fallidas no consumen créditos.
Crear API Key1. Guardar la API Key
Resultado esperado: la CLI solicita la Key sin mostrarla y después indica keyring o config como ubicación. Si el almacén de credenciales del sistema no está disponible, usa tu archivo de configuración de PoYo.
npx -y @poyoapi/cli auth login2. Verificar cuenta y saldo
Resultado esperado: datos de la cuenta y saldo disponible. Un 401 significa que la Key falta o no es válida.
npx -y @poyoapi/cli account3. Confirmar el precio y ejecutar
Esta es una solicitud de pago. Un resultado JSON correcto incluye task_id, estado final y archivos de salida.
npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --format jsonConvierte el Schema del modelo en argumentos CLI
Antes de chat, run o submit, la CLI lee el Schema del modelo elegido y convierte sus campos en argumentos específicos.
Busca antes de ejecutar
models muestra el catálogo público. describe devuelve Schema, protocolos, modo de ejecución, callbacks y cobro.
Estos dos comandos no requieren API Key.
Prompt de generación
Un campo de texto del Schema se acepta como valor normal de terminal.
Las opciones desconocidas fallan localmente. La validación completa de JSON Schema sigue realizándose en la API.
Vuelve ahora y recupera después
submit devuelve un task_id. task get consulta el estado y task wait sigue esperando.
Adecuado para vídeo, audio, 3D y otras tareas largas.
Controla cómo devuelve resultados la CLI
El chat en streaming escribe texto o JSONL en stdout. Los comandos sin streaming pueden devolver table, JSON, JSONL o CSV y escribir el resultado en un archivo.
La CLI usa los mismos endpoints y reglas de cobro que REST API.
Elige el comando adecuado para cada tarea
Comandos independientes gestionan el descubrimiento de modelos, el chat, la generación, la recuperación de tareas y el puente MCP local.
~/projects/poyo-demo
# 1. Elegir un modelo
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
# 2. Entrada de comando generada
$ npx -y @poyoapi/cli describe gpt-image-2
prompt string required
size string default: "1:1"
output_format string enum: jpeg | png
# 3. Autenticar y ejecutar
$ npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --size 4:3 --output-format png --format json
{
"task_id": "task_7f31b2",
"status": "succeeded",
"files": ["https://storage.poyo.ai/.../image.png"]
}Ciclo de la tarea
Continúa tareas largas con task_id
PoYo devuelve directamente el estado público existente de la tarea. Si la CLI agota el tiempo o se cierra, consulta la misma tarea en lugar de enviarla de nuevo.
Un timeout de la CLI no cancela la tarea del backend. Reutiliza el mismo task_id en vez de pagar una solicitud duplicada.
Usa submit para trabajos largos
$ npx -y @poyoapi/cli submit gpt-image-2 --prompt "cinematic product photo" --format jsontask_id task_7f31b2
$ npx -y @poyoapi/cli task wait TASK_ID --timeout 300 --format jsonstatus succeeded
Usa run para una espera limitada
run consulta cada dos segundos y espera hasta 90 segundos por defecto.
Usa submit para trabajos largos
Guarda el task_id y usa task get o task wait desde otra terminal o paso de CI.
Elige entre CLI, MCP, REST y Skill
Usa CLI en terminales y CI, MCP para llamadas de herramientas del Agent, REST API en aplicaciones y Skill para flujos de Agent repetibles.
PoYo CLI
Desarrolladores, terminal y CI
Una persona o script necesita descubrir, ejecutar, recuperar y leer códigos de salida.
Instalar CLIMCP
Agents de IA y clientes de código
Un Agent debe descubrir Schema, precios y herramientas desde una conexión.
Ver MCPREST API
Aplicaciones y servicios
Tu producto controla orquestación, streaming, reintentos y tráfico.
Abrir docsPoYo Skill
Flujos de Agent repetibles
Un Agent necesita instrucciones y reglas de seguridad además de interfaces.
Ver SkillPreguntas sobre PoYo CLI
¿Aún dudas sobre un comando? Contactar con soporte de PoYo→
PoYo CLI es un cliente de línea de comandos basado en el catálogo para descubrir y llamar a modelos de chat, imagen, vídeo, audio y 3D de PoYo. Lee el Capability Catalog en tiempo real, convierte campos Schema en opciones de comando y usa los mismos endpoints de PoYo para ejecutar y consultar tareas.
models y describe leen el Capability Catalog público. Chat, generación, tareas, cuenta y ejecución de pago requieren API Key.
run espera 90 segundos por defecto. El timeout no cancela la tarea del backend. Continúa con npx -y @poyoapi/cli task wait TASK_ID.
Guárdala en el gestor de secretos de CI y expón POYO_API_KEY. Fija @poyoapi/cli@VERSION, solicita --format json y trata cualquier código de salida distinto de cero como error. No la incluyas en el repositorio.
No. La CLI usa los mismos endpoints. describe muestra el precio público y account el saldo actual. run y submit son de pago; los créditos solo se descuentan cuando la generación tiene éxito. 401 indica una Key ausente o no válida y 402 saldo insuficiente.
Un puente stdio reenvía JSON-RPC a https://api.poyo.ai/mcp. La ejecución del modelo sigue siendo remota.
Ejecuta tu primer modelo de PoYo desde la terminal
Explora primero el catálogo público y crea una API Key cuando estés listo para ejecutar un modelo.