CLI

Instale la versión actual en Linux o macOS:

Las instalaciones de Homebrew y desde el código fuente de Go también están disponibles:

En Windows, descargue el archivo windows-amd64 o windows-arm64 correspondiente desde la última versión de la CLI, extraiga runapi.exe y agréguelo a PATH.

Fije el instalador a una versión o a un directorio de instalación cuando una implementación requiera un binario reproducible:

El instalador también acepta RUNAPI_VERSION, RUNAPI_INSTALL_DIR, RUNAPI_INSTALL_BASE, RUNAPI_DOWNLOAD_BASE y RUNAPI_SKIP_LIBC_CHECK=1.

En una estación de trabajo, inicie sesión en el navegador y confirme la fuente de credenciales:

Ejecute una acción de modelo con una entrada JSON en línea o un archivo JSON:

La mayoría de las acciones del modelo son asíncronas. Esperan un resultado terminal de forma predeterminada; agregue --async para devolver la Tarea inmediatamente y use wait más tarde:

Cada comando emite JSON en la salida estándar a menos que una opción solicite explícitamente un valor escalar, como files create --url-only o listen --print-secret. Los mensajes de progreso y diagnóstico permanecen en el error estándar, por lo que JSON puede fluir de forma segura a jq:

Las acciones del modelo aceptan exactamente una fuente de entrada de solicitud:

Usa runapi <service> <action> --help antes de construir una solicitud. La CLI instalada lista los campos actuales de la acción, los identificadores de modelo aceptados y las restricciones de validación.

Estas opciones globales se aplican a todos los comandos:

La forma del comando de modelo es runapi <service> <action>. Las acciones síncronas devuelven su respuesta de inmediato. Para las acciones asíncronas, el comportamiento predeterminado es enviar, sondear y devolver el resultado terminal de la tarea; --async devuelve en su lugar la respuesta de creación.

Para los campos de URL de medios de nivel superior, se carga una ruta de archivo local legible antes de que se ejecute la acción del modelo. Las URL http:// y https:// existentes se envían sin cambios. Use files create cuando necesite una URL temporal reutilizable, cuando el origen sea una URL remota o cuando el origen sean datos Base64.

La lista anterior es el inventario completo de acciones en esta versión de la CLI. El contrato exacto de solicitud y respuesta de cada acción está disponible en la Referencia de la API, y la ayuda del comando local es la fuente para los campos específicos de cada versión.

Usa get para inspeccionar el estado actual de una Task asíncrona sin esperar. Usa wait para sondear hasta que se complete, falle o alcance el tiempo de espera del comando. Ambos comandos requieren el servicio y la acción originales para que la CLI pueda seleccionar la forma de resultado de Task correcta.

runapi files create mantiene el flujo de URL de File Upload temporal. Sube una ruta local, URL remota o fuente Base64 y devuelve una URL que expira después de una hora.

Las opciones de origen son mutuamente excluyentes. --url-only imprime únicamente la URL; omítelo para recibir la respuesta JSON completa.

Usa el ciclo de vida de archivo persistente cuando necesites un file_id estable en lugar de una URL:

content requiere --output; pasa - para escribir los bytes exactos del File en la salida estándar. Consulta Files and Uploads para conocer los límites, el aislamiento de cuenta y el ciclo de vida REST.

Usa Uploads para enviar una o más Parts antes de componer el File final. Create declara el recuento final de bytes y los metadatos; repite --part-id en el orden de composición al completar:

Inspeccione el usuario autenticado y la cuenta seleccionada, luego consulte el saldo y los contadores de gasto:

pricing list lee los Price Schedules actuales. Filtra por servicio, acción o modelo. pricing quote estima la reserva de Task para un servicio y acción requeridos; agrega --model cuando la acción es específica del modelo y proporciona los Pricing Inputs con --params o --params-file.

Los comandos de precios no requieren credenciales a menos que la cotización haga referencia a una tarea de origen de propiedad de la cuenta.

runapi login abre un flujo de autorización en el navegador y guarda la credencial resultante. Para servidores y CI, auth import-token acepta una Clave de API desde la entrada estándar, la verifica de forma predeterminada y la guarda sin exponer el valor en la lista de procesos ni en el historial del shell:

auth import-token --skip-verify admite la configuración de imágenes sin conexión. Úsalo solo cuando la verificación no pueda ejecutarse durante la configuración; auth status verifica la credencial activa más adelante.

La precedencia de la Clave de API es --api-key, luego RUNAPI_API_KEY, luego el archivo de configuración local de la CLI. La precedencia de la URL base es --base-url, luego RUNAPI_BASE_URL, luego la URL base guardada, luego https://runapi.ai. El archivo de configuración es ~/.config/runapi/config.json, o $XDG_CONFIG_HOME/runapi/config.json cuando XDG_CONFIG_HOME está definido.

runapi listen recibe devoluciones de llamada de Task para una Clave de API seleccionada y, opcionalmente, reenvía cada devolución de llamada firmada a un endpoint HTTP local. Es necesario iniciar sesión en el navegador antes de usar las operaciones de escucha.

La URL posicional y --forward-to son alternativas. El listener escribe cada cuerpo de devolución de llamada firmado en la salida estándar. Una tarea con callback_url continúa entregando a esa URL y también se copia al listener local.

Después de recibir un evento de escucha válido, la CLI lo confirma antes de intentar la solicitud HTTP local. Cada evento se reenvía localmente una vez: las respuestas que no son 2xx y los errores de conexión se informan en la terminal, pero no hacen que el listener reproduzca el evento. Este comportamiento de depuración local no modifica los reintentos de entrega para la callback_url de una tarea.

Cada cuenta puede ejecutar hasta 100 listeners activos por clave de suscripción de devoluciones de llamada y 1 000 listeners activos en total. Cuando se alcanza un límite, detenga un listener inactivo o espere e inténtelo de nuevo. La respuesta de la API indica si la clave seleccionada, su cuenta o la capacidad general del servicio está llena.

Un listener inactivo busca nuevos eventos aproximadamente cada 15 a 30 segundos. Normalmente los eventos se encuentran en unos 15 segundos y se leen inmediatamente cuando están disponibles. Si se alcanza un límite, detén un listener inactivo o espera e inténtalo de nuevo. El comportamiento de entrega y confirmación existente no cambia.

La selección de clave es, en orden: --callback-api-key-id para un comando, callback_api_key_id en el proyecto .runapi.toml, luego un selector interactivo. La configuración del proyecto se guarda en la raíz de Git, o en el directorio actual fuera de un repositorio de Git, y contiene solo el ID estable:

Imprima el secreto de firma de escucha de una clave seleccionada sin iniciar un oyente, o rótelo tras una exposición:

La rotación invalida los listeners activos de la clave seleccionada. Actualice cada verificador local con el nuevo secreto generado antes de reiniciar su listener.

Instale la habilidad portátil de la CLI de RunAPI en un Harness compatible, inspeccione los destinos admitidos o elimine una habilidad instalada:

Los destinos integrados son claude, codex, gemini, openclaw y hermes. install-skill acepta --version para fijar una versión de skill, --target-dir para un destino personalizado, --source para un repositorio de origen, y --force para sobrescribir un directorio de skill existente.

Genere scripts de completado para Bash, Zsh, Fish o PowerShell. Por ejemplo, cargue el completado de Bash en el shell actual:

Usa runapi --help para listar los comandos, runapi <command> --help para las opciones de un comando, y runapi <service> <action> --help para los campos de una acción de modelo.

Los comandos salen con un código distinto de cero que los scripts pueden gestionar:

Para los campos de solicitud, los valores de estado de Task, las cargas útiles de devolución de llamada, los cuerpos de error y el manejo de límites de velocidad, continúe con la Referencia de la API. Use los SDK cuando el mismo flujo de trabajo pertenezca a una aplicación.