CLI

Instale a versão atual no Linux ou macOS:

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

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

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:

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

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

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

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:

As ações de modelo aceitam exatamente uma fonte de entrada de requisiçã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:

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 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, e a ajuda do comando local é a fonte para os campos específicos da versão.

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.

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.

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:

content requer --output; passe - para gravar os bytes exatos do File na saída padrão. Consulte Files and Uploads para limites, isolamento de conta e o ciclo de vida REST.

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:

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

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.

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

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:

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.

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.

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:

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

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

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

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.

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

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.

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

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. Use SDKs quando o mesmo fluxo de trabalho pertencer a uma aplicação.