---
title: CLI | RunAPI
description: Instale y use todos los comandos de la CLI de RunAPI para acciones de
  modelo, Tasks, archivos, cargas, información de cuenta, precios, devoluciones de
  llamada y Harness.
url: https://runapi.ai/es/docs/resources/cli.md
canonical: https://runapi.ai/es/docs/resources/cli
locale: es
---

> Versión HTML: https://runapi.ai/es/docs/resources/cli
> Índice del sitio para agentes: https://runapi.ai/llms.txt

# CLI

La CLI de RunAPI es un cliente de terminal basado en JSON para acciones de modelos y herramientas de cuenta. Escribe los datos de resultados en la salida estándar y el progreso operativo en el error estándar, por lo que funciona igualmente bien en una terminal, en scripts de shell, en trabajos de CI y en Harness.

## Instalar

Instale la versión actual en Linux o macOS:

```shell
curl -fsSL https://runapi.ai/cli/install.sh | sh
```

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

```shell
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest
```

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



[1]: https://github.com/runapi-ai/cli/releases/latest

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

```shell
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --version v0.13.1
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --dir "$HOME/.local/bin"
```

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

## Inicio rápido

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

```shell
runapi login
runapi auth status
```

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

```shell
runapi nano-banana text-to-image --input '{"prompt":"a hummingbird drinking espresso","aspect_ratio":"1:1"}'
runapi nano-banana text-to-image --input-file request.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:

```shell
TASK_ID=$(runapi suno text-to-music --async --input '{"model":"suno-v5","vocal_mode":"instrumental","style":"minimal piano","title":"Short Piano Theme"}' | jq -r '.id')
runapi wait "$TASK_ID" --service suno --action text-to-music
```

## Convenciones de comandos

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

```shell
runapi nano-banana text-to-image --input-file request.json \
  | jq -r '.images[].url' \
  | xargs -I{} curl -OL {}
```

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

* `--input '<json object>'` proporciona JSON en línea.
* `--input-file path/to/request.json` carga JSON desde un archivo.
* `--input-file -` lee JSON desde la entrada estándar.

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:

| Opción | Propósito |
|----------
| `--api-key` | Usa una clave de API para esta invocación. Reemplaza a `RUNAPI_API_KEY`. |
| `--base-url` | Usa un origen de API diferente para esta invocación. |
| `--timeout` | Establece el tiempo de espera total del comando y el máximo de espera de una tarea. El valor predeterminado es 15 minutos. |
| `--poll-interval` | Establece el intervalo de sondeo de tareas. El valor predeterminado es 3 segundos. |
| `--async` | Devuelve el resultado inmediatamente tras enviar una acción de modelo asíncrona. |
| `--quiet` | Suprime el progreso en la salida de error estándar sin modificar la salida JSON. |

## Acciones del modelo

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.

### Acciones de audio y música

* `suno`: `add-instrumental`, `add-vocals`, `blend-lyrics`,
  `boost-style`, `check-voice`, `convert-audio`, `cover-audio`,
  `create-mashup`, `extend-music`, `generate-artwork`,
  `generate-lyrics`, `generate-midi`, `generate-persona`,
  `generate-voice`, `get-timestamped-lyrics`,
  `regenerate-validation-phrase`, `replace-section`,
  `separate-audio-stems`, `text-to-music`, `text-to-sound`,
  `visualize-music`, `voice-to-validation-phrase`
* `producer`: `text-to-music`
* `gemini-omni`: `create-audio`, `create-character`, `text-to-video`
* `openai-tts`: `text-to-speech`
* `fish-audio`: `text-to-speech`
* `gemini-tts`: `text-to-speech`
* `elevenlabs`: `isolate-audio`, `speech-to-text`, `text-to-dialogue`,
  `text-to-sound`, `text-to-speech`

### Acciones de imagen

* `nano-banana`: `edit-image`, `text-to-image`
* `imagen-4`: `remix-image`, `text-to-image`
* `seedream`: `decompose-layers`, `edit-image`, `text-to-image`
* `flux`: `remix-image`, `text-to-image`
* `flux-2`: `remix-image`, `text-to-image`
* `flux-kontext`: `text-to-image`
* `qwen-2`: `edit-image`, `text-to-image`
* `qwen-3`: `edit-image`, `text-to-image`
* `qwen-image`: `edit-image`, `remix-image`, `text-to-image`
* `recraft`: `remove-background`, `upscale-image`
* `z-image`: `text-to-image`
* `ideogram-v3`: `edit-image`, `reframe-image`, `remix-image`,
  `text-to-image`
* `gpt-image`: `edit-image`, `text-to-image`
* `gpt-image-2`: `edit-image`, `text-to-image`
* `gpt-4o-image`: `text-to-image`
* `midjourney`: `edit-image`, `get-seed`, `image-to-prompt`,
  `shorten-prompt`, `text-to-image`

### Acciones de video y animación

* `veo-3-1`: `extend-video`, `text-to-video`, `upscale-video`
* `seedance`: `text-to-video`
* `runway`: `extend-video`, `text-to-video`
* `runway-aleph`: `edit-video`
* `kling`: `avatar`, `edit-video`, `extend-video`, `image-to-video`,
  `motion-control`, `text-to-video`
* `infinitetalk`: `audio-to-video`
* `omnihuman`: `audio-to-video`, `human-identification`,
  `subject-detection`
* `wan`: `animate`, `edit-video`, `image-to-video`, `speech-to-video`,
  `text-to-image`, `text-to-video`
* `luma`: `modify-video`
* `hailuo`: `image-to-video`, `text-to-video`
* `volcengine-lip-sync`: `lip-sync-video`
* `happyhorse`: `edit-video`, `image-to-video`, `text-to-video`
* `grok-imagine`: `edit-image`, `extend`, `image-to-video`,
  `text-to-image`, `text-to-video`, `upscale-image`
* `topaz`: `upscale-image`, `upscale-video`
* `midjourney`: `extend-video`, `image-to-video`

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](https://runapi.ai/es/docs/api/openai/chat-completions.md), y la ayuda del comando local es la fuente para los campos específicos de cada versión.

## Ciclo de vida de la tarea

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.

```shell
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s
```

## Archivos

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

```shell
runapi files create ./reference.png --url-only
runapi files create --url https://example.test/reference.png --file-name reference.png
runapi files create --base64 "$(base64 < reference.png)" --file-name reference.png
```

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:

```shell
runapi files create-file ./knowledge.pdf
runapi files list --order desc
runapi files retrieve file_123
runapi files content file_123 --output ./knowledge-copy.pdf
runapi files delete file_123
```

`content` requiere `--output`; pasa `-` para escribir los bytes exactos del File en la salida estándar. Consulta [Files and Uploads](https://runapi.ai/es/docs/resources/files.md) para conocer los límites, el aislamiento de cuenta y el ciclo de vida REST.

## Cargas

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:

```shell
runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream
runapi uploads add-part upload_123 ./archive.part-01
runapi uploads complete upload_123 --part-id part_123
runapi uploads cancel upload_123
```

## Cuenta y precios

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

```shell
runapi account info
runapi account balance
```

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

```shell
runapi pricing list --service suno --action text-to-music --model suno-v4
runapi pricing quote --service suno --action text-to-music --model suno-v4 \
  --params '{"vocal_mode":"auto_lyrics","prompt":"A chill lo-fi beat"}'
runapi pricing quote --service suno --action text-to-music --params-file pricing-inputs.json
```

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.

## Autenticación y configuración

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

```shell
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout
```

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

## Oyente de devolución de llamada local

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

```shell
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
```

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:

```toml
callback_api_key_id = "token_abc123"
```

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

```shell
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
```

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.

## Arnés

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

```shell
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex
```

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.

## Autocompletado del shell y versión

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

```shell
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version
```

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.

## Códigos de salida

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

| Código | Significado |
|----------
| `0` | Éxito |
| `2` | Error de autenticación o plataforma no compatible |
| `3` | Créditos insuficientes o falta una dependencia local requerida |
| `4` | Error de validación, recurso no encontrado o error al analizar el manifiesto |
| `5` | Tiempo de espera agotado, error de descarga o discrepancia en la suma de verificación |
| `6` | Límite de solicitudes superado |
| `7` | La tarea falló |

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](https://runapi.ai/es/docs/api/openai/chat-completions.md). Use los
[SDK](https://runapi.ai/es/docs/resources/sdks.md) cuando el mismo flujo de trabajo pertenezca a una
aplicación.

---

## Más de RunAPI

- [Inicio](https://runapi.ai/es/.md)
- [Catálogo de modelos](https://runapi.ai/es/models.md)
- [Precios](https://runapi.ai/es/pricing.md)
- [Proveedores](https://runapi.ai/es/models)
- [Documentación](https://runapi.ai/es/docs/guides)
- [SDKs](https://runapi.ai/es/sdk.md)
- [CLI](https://runapi.ai/es/cli.md)
- [Servidor MCP](https://runapi.ai/es/mcp.md)
- [Claude Code vs Cursor](https://runapi.ai/es/claude-code-vs-cursor.md)
- [Configuración de Cursor API](https://runapi.ai/es/cursor-api-setup.md)
- [RunAPI vs OpenRouter](https://runapi.ai/es/openrouter-alternative.md)
- [Enterprise](https://runapi.ai/es/contact.md)
- [Contacto](https://runapi.ai/es/contact.md)
- [Términos](https://runapi.ai/es/terms.md)
- [Privacidad](https://runapi.ai/es/privacy.md)
- [Índice del sitio para agentes](https://runapi.ai/llms.txt)

Contacto: contact@runapi.ai

## Datos estructurados

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "es",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/es",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/es/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "es",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/es",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/esicon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "es",
    "@type": "TechArticle",
    "headline": "CLI",
    "description": "Instale y use todos los comandos de la CLI de RunAPI para acciones de modelo, Tasks, archivos, cargas, información de cuenta, precios, devoluciones de llamada y Harness.",
    "url": "https://runapi.ai/es/docs/resources/cli",
    "mainEntityOfPage": "https://runapi.ai/es/docs/resources/cli"
  }
]
```