---
title: CLI | RunAPI
description: Instale e use todos os comandos da CLI do RunAPI para ações de modelo,
  Tasks, Files, Uploads, informações de conta, preços, Callbacks e Harness.
url: https://runapi.ai/pt-BR/docs/resources/cli.md
canonical: https://runapi.ai/pt-BR/docs/resources/cli
locale: pt-BR
---

> Versão HTML: https://runapi.ai/pt-BR/docs/resources/cli
> Índice do site para agentes: https://runapi.ai/llms.txt

# CLI

A CLI do RunAPI é um cliente de terminal com foco em JSON para ações de modelo e ferramentas de conta. Ela grava os dados de resultado na saída padrão e o progresso operacional no erro padrão, funcionando igualmente bem em um terminal, em scripts de shell, jobs de CI e no Harness.

## Instalar

Instale a versão atual no Linux ou macOS:

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

Instalações via Homebrew e a partir do código-fonte com Go também estão disponíveis:

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

No Windows, baixe o arquivo `windows-amd64` ou `windows-arm64`
correspondente da [versão mais recente da CLI][1], extraia o `runapi.exe` e adicione-o
ao `PATH`.



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

Fixe o instalador em uma versão ou em um diretório de instalação quando uma
implantação exigir um binário reproduzível:

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

O instalador também aceita `RUNAPI_VERSION`, `RUNAPI_INSTALL_DIR`, `RUNAPI_INSTALL_BASE`, `RUNAPI_DOWNLOAD_BASE` e `RUNAPI_SKIP_LIBC_CHECK=1`.

## Início rápido

Em uma estação de trabalho, faça login no navegador e confirme a origem da credencial:

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

Execute uma ação de modelo com uma entrada JSON inline ou um arquivo 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
```

A maioria das ações de modelo é assíncrona. Por padrão, elas aguardam um resultado
terminal; adicione `--async` para retornar a Task imediatamente e use `wait`
posteriormente:

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

## Convenções de comandos

Cada comando emite JSON na saída padrão, a menos que uma opção solicite explicitamente um valor escalar, como `files create --url-only` ou `listen
--print-secret`. Mensagens de progresso e diagnóstico ficam no erro padrão, para que o JSON possa ser encaminhado com segurança para `jq`:

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

As ações de modelo aceitam exatamente uma fonte de entrada de requisição:

* `--input '<json object>'` fornece JSON inline.
* `--input-file path/to/request.json` carrega JSON a partir de um arquivo.
* `--input-file -` lê JSON da entrada padrão.

Use `runapi <service> <action> --help` antes de construir uma requisição.
A CLI instalada lista os campos atuais da ação, os identificadores de modelo aceitos
e as restrições de validação.

Estas opções globais se aplicam a todos os comandos:

| Opção | Finalidade |
|----------
| `--api-key` | Usa uma Chave de API para esta invocação. Substitui `RUNAPI_API_KEY`. |
| `--base-url` | Usa uma origem de API diferente para esta invocação. |
| `--timeout` | Define o tempo limite geral do comando e o tempo máximo de espera de Tarefa. O padrão é 15 minutos. |
| `--poll-interval` | Define o intervalo de polling de Tarefa. O padrão é 3 segundos. |
| `--async` | Retorna imediatamente após enviar uma ação de modelo assíncrona. |
| `--quiet` | Suprime o progresso na saída de erro padrão sem alterar a saída JSON. |

## Ações de modelo

A forma do comando de modelo é `runapi <service> <action>`. Ações síncronas retornam a resposta imediatamente. Para ações assíncronas, o comportamento padrão é enviar, fazer polling e retornar o resultado terminal da Tarefa; `--async` retorna a resposta de criação em vez disso.

Para campos de URL de mídia de nível superior, um caminho de arquivo local legível é enviado por upload antes que a ação do modelo seja executada. URLs `http://` e `https://` existentes são enviadas sem alteração. Use `files create` quando precisar de uma URL temporária reutilizável, quando a origem for uma URL remota ou quando a origem for dados em Base64.

### Ações de áudio e 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`

### Ações de imagem

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

### Ações de vídeo e animação

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

A lista acima é o inventário completo de ações nesta versão da CLI. O contrato exato de requisição e resposta de cada ação está disponível na [Referência da API](https://runapi.ai/pt-BR/docs/api/openai/chat-completions.md), e a ajuda do comando local é a fonte para os campos específicos da versão.

## Ciclo de vida da tarefa

Use `get` para inspecionar o estado atual de uma Task assíncrona sem
aguardar. Use `wait` para fazer polling até que ela seja concluída, falhe ou atinja o
tempo limite do comando. Ambos os comandos exigem o serviço e a ação originais
para que a CLI possa selecionar o formato correto do resultado da Task.

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

## Arquivos

`runapi files create` mantém o fluxo de URL de Upload de File temporário. Ele
faz upload de um caminho local, URL remota ou fonte Base64 e retorna uma URL
que expira após uma 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
```

As opções de fonte são mutuamente exclusivas. `--url-only` imprime somente a URL; omita-a para receber a resposta JSON completa.

Use o ciclo de vida de Arquivo persistente quando precisar de um `file_id`
estável em vez de uma 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` requer `--output`; passe `-` para gravar os bytes exatos do File na
saída padrão. Consulte [Files and Uploads](https://runapi.ai/pt-BR/docs/resources/files.md) para
limites, isolamento de conta e o ciclo de vida REST.

## Uploads

Use Uploads para enviar uma ou mais Parts antes de compor o File final.
Create declara a contagem final de bytes e os metadados; repita `--part-id` na
ordem de composição ao 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
```

## Conta e preços

Inspecione o usuário autenticado e a Conta selecionada, depois consulte o saldo
e os contadores de gastos:

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

`pricing list` lê os Agendamentos de Preço atuais. Filtre por serviço, ação
ou modelo. `pricing quote` estima a reserva de Task para um serviço e ação
necessários; adicione `--model` quando a ação for específica de modelo e
forneça Pricing Inputs com `--params` ou `--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
```

Comandos de precificação não exigem credenciais, a menos que a cotação se refira
a uma Tarefa de origem pertencente à Conta.

## Autenticação e configuração

`runapi login` abre um fluxo de autorização pelo navegador e salva a
credencial resultante. Para servidores e CI, `auth import-token` aceita uma
Chave de API da entrada padrão, verifica-a por padrão e a salva
sem expor o valor na lista de processos ou no histórico do shell:

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

`auth import-token --skip-verify` oferece suporte à configuração de imagem offline. Use-o
somente quando a verificação não puder ser executada durante a configuração; `auth status` verifica
a credencial ativa posteriormente.

A precedência da Chave de API é `--api-key`, depois `RUNAPI_API_KEY`, depois o arquivo
de configuração local da CLI. A precedência da Base URL é `--base-url`, depois
`RUNAPI_BASE_URL`, depois a URL base salva, depois `https://runapi.ai`.
O arquivo de configuração é `~/.config/runapi/config.json`, ou
`$XDG_CONFIG_HOME/runapi/config.json` quando `XDG_CONFIG_HOME` estiver definido.

## Listener de callback local

`runapi listen` recebe callbacks de Task para uma Chave de API selecionada e
opcionalmente encaminha cada callback assinado para um endpoint HTTP local.
O login pelo navegador é obrigatório antes de usar operações de listener.

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

A URL posicional e `--forward-to` são alternativas. O listener grava cada corpo de callback assinado na saída padrão. Uma Tarefa com `callback_url` continua a entregar para aquela URL e também é copiada para o listener local.

Após receber um evento de listener válido, a CLI o reconhece antes de
tentar a requisição HTTP local. Cada evento é encaminhado localmente uma vez:
respostas não-2xx e erros de conexão são reportados no terminal,
mas não fazem o listener reenviar o evento. Esse comportamento de depuração local
não altera as tentativas de entrega para o `callback_url` de uma Tarefa.

Cada Conta pode ter até 100 listeners ativos por Chave de Assinatura de Callback e 1.000 listeners ativos no total. Quando um limite for atingido, pare um listener ocioso ou aguarde e tente novamente. A resposta da API identifica se a chave selecionada, sua Conta ou a capacidade geral do serviço está esgotada.

Um listener ocioso verifica novos eventos aproximadamente a cada 15 a 30 segundos.
Os eventos são normalmente encontrados em cerca de 15 segundos e são lidos
imediatamente quando disponíveis. Se um limite for atingido, interrompa um listener
ocioso ou aguarde e tente novamente. O comportamento existente de entrega e reconhecimento permanece inalterado.

A seleção da chave segue esta ordem: `--callback-api-key-id` para um único comando,
`callback_api_key_id` no `.runapi.toml` do projeto e, em seguida, um seletor interativo. A configuração do projeto é salva na raiz do Git, ou no diretório atual fora de um repositório Git, e contém apenas o ID estável:

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

Imprima o Segredo de Assinatura de Escuta de uma chave selecionada sem iniciar um
listener, ou substitua-o após exposição:

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

A rotação invalida os listeners ativos da chave selecionada. Atualize
cada verificador local com o novo segredo gerado antes de reiniciar seu
listener.

## Harness

Instale a skill portátil da CLI do RunAPI em um Harness compatível, inspecione os alvos suportados ou remova uma skill instalada:

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

Os alvos integrados são `claude`, `codex`, `gemini`, `openclaw` e
`hermes`. O comando `install-skill` aceita `--version` para fixar uma versão de skill,
`--target-dir` para um destino personalizado, `--source` para um repositório de origem,
e `--force` para sobrescrever um diretório de skill existente.

## Completação de shell e versão

Gere scripts de conclusão para Bash, Zsh, Fish ou PowerShell. Por
exemplo, carregue a conclusão do Bash no shell atual:

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

Use `runapi --help` para listar os comandos, `runapi <command> --help` para as
opções de um comando e `runapi <service> <action> --help` para os campos de uma
ação de modelo.

## Códigos de saída

Os comandos encerram com um código diferente de zero que scripts podem tratar:

| Código | Significado |
|----------
| `0` | Sucesso |
| `2` | Falha de autenticação ou plataforma não suportada |
| `3` | Créditos insuficientes ou uma dependência local necessária está ausente |
| `4` | Erro de validação, não encontrado ou falha na análise do manifesto |
| `5` | Tempo limite excedido, falha no download ou incompatibilidade de checksum |
| `6` | Limite de taxa atingido |
| `7` | Tarefa falhou |

Para campos de requisição, valores de status de Task, payloads de Callbacks, corpos de erro
e tratamento de limite de taxa, continue com a [Referência da
API](https://runapi.ai/pt-BR/docs/api/openai/chat-completions.md). Use
[SDKs](https://runapi.ai/pt-BR/docs/resources/sdks.md) quando o mesmo fluxo de trabalho pertencer a uma
aplicação.

---

## Mais de RunAPI

- [Início](https://runapi.ai/pt-BR/.md)
- [Catálogo de modelos](https://runapi.ai/pt-BR/models.md)
- [Preços](https://runapi.ai/pt-BR/pricing.md)
- [Provedores](https://runapi.ai/pt-BR/models)
- [Documentação](https://runapi.ai/pt-BR/docs/guides)
- [SDKs](https://runapi.ai/pt-BR/sdk.md)
- [CLI](https://runapi.ai/pt-BR/cli.md)
- [Servidor MCP](https://runapi.ai/pt-BR/mcp.md)
- [Claude Code vs Cursor](https://runapi.ai/pt-BR/claude-code-vs-cursor.md)
- [Configuração da API do Cursor](https://runapi.ai/pt-BR/cursor-api-setup.md)
- [RunAPI vs OpenRouter](https://runapi.ai/pt-BR/openrouter-alternative.md)
- [Enterprise](https://runapi.ai/pt-BR/contact.md)
- [Contato](https://runapi.ai/pt-BR/contact.md)
- [Termos](https://runapi.ai/pt-BR/terms.md)
- [Privacidade](https://runapi.ai/pt-BR/privacy.md)
- [Índice do site para agentes](https://runapi.ai/llms.txt)

Contato: contact@runapi.ai

## Dados estruturados

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "pt-BR",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/pt-BR",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/pt-BR/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "pt-BR",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/pt-BR",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/pt-BRicon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "pt-BR",
    "@type": "TechArticle",
    "headline": "CLI",
    "description": "Instale e use todos os comandos da CLI do RunAPI para ações de modelo, Tasks, Files, Uploads, informações de conta, preços, Callbacks e Harness.",
    "url": "https://runapi.ai/pt-BR/docs/resources/cli",
    "mainEntityOfPage": "https://runapi.ai/pt-BR/docs/resources/cli"
  }
]
```