OpenAI CLI: Como Instalar e Chamar a API da OpenAI no Terminal

O OpenAI CLI é a ferramenta de linha de comando oficial da OpenAI para a API REST da OpenAI. Você instala um único binário openai, define OPENAI_API_KEY e chama a API a partir do seu terminal ou de um script de shell: openai responses create, openai files upload, openai batches create, openai images generate. Ele não é o Codex CLI. O Codex é um agente de programação; o openai envia uma requisição de API por comando.

Experimente o Apidog hoje

Este guia aborda instalação, autenticação, os primeiros comandos que vale a pena executar e como ele se compara com o Codex CLI e com o antigo comando openai que o SDK Python colocava no seu PATH. Todos os comandos e saídas abaixo vêm da versão 1.44.1, instalada e executada em 28 de outubro de 2026.

O que é o OpenAI CLI?

O OpenAI CLI é um binário Go de código aberto, publicado pela OpenAI em github.com/openai/openai-cli sob a licença Apache 2.0. Seus comandos espelham os recursos da API (responses, files, batches, images, audio, vector-stores, admin), então qualquer coisa que você enviaria com curl ou um SDK se torna um único comando de terminal com flags.

Ele não é novidade. A versão 1.0.0 foi lançada em 5 de maio de 2026, e o projeto já publicou 99 releases desde então; a 1.44.1 saiu em 27 de outubro de 2026. Portanto, trate-o como uma ferramenta madura que você pode ter deixado passar, não como um lançamento.

Veja o que você obtém na primeira execução:

O help agrupa os comandos por função: gerar conteúdo (responses, chat, images, audio, videos), dados e recuperação (files, uploads, vector-stores, embeddings), modelos e jobs, administração e um conjunto de ferramentas locais que nunca acessam a rede. O próprio help não precisa de chave de API nem de conexão, o que faz de openai <command> --help a forma mais rápida de aprender as flags.

Ele é indicado para desenvolvedores testando um prompt sem escrever um script, profissionais de operações que querem uploads de arquivos e batches em um cron job, e agentes de programação que precisam de uma interface documentada em vez de curl feito à mão.

Como instalar o OpenAI CLI

Você tem três rotas de instalação, todas listadas no README do projeto:

1. Binário pré-compilado. Baixe o arquivo para seu SO e arquitetura em GitHub Releases (builds para macOS, Linux e Windows são publicados), extraia-o e coloque openai no seu PATH.
2. Homebrew.

brew install openai/tools/openai

1. Go. Requer Go 1.26 ou posterior.

go install 'github.com/openai/openai-cli/cmd/openai@latest'
export PATH="$PATH:$(go env GOPATH)/bin"

Instalações de release autogerenciadas podem se atualizar durante execuções interativas. Se você fixa versões em CI, defina OPENAI_CLI_NO_AUTO_UPDATE=1 para impedir instalações automáticas, ou OPENAI_CLI_NO_UPDATE_CHECK=1 para desativar completamente as verificações de atualização. Instalações via Homebrew e Go mantêm seus avisos de atualização, mas deixam as atualizações para o gerenciador de pacotes.

Como funciona a autenticação do OpenAI CLI

O CLI lê uma chave de API padrão de OPENAI_API_KEY (ou da flag --api-key, que você deve evitar porque ela fica no histórico do shell). Se você ainda não tem uma, nosso guia sobre como obter uma chave de API da OpenAI mostra o passo a passo.

A configuração mais rápida é o guia integrado:

openai help setup

Ele direciona você para a página de chaves de API e fornece uma linha read -rs OPENAI_API_KEY para Bash ou zsh, para que a chave seja digitada oculta e nunca seja exibida.

Esqueça a chave e você receberá uma falha clara e scriptável. Esta é a saída real sem nenhuma chave definida:

Ele sai com status 1 e informa exatamente de onde uma chave pode vir. Adicione --format-error json quando um script precisar do corpo bruto do erro.

As outras configurações de autenticação:

Primeiros comandos do OpenAI CLI para executar

A forma do comando segue a API: openai <resource> [subresource...] <command> [flags...]. Estes são os comandos que ganham seu lugar em uma caixa de ferramentas.

Faça uma chamada à API Responses

openai responses create \
  --model gpt-5.5 \
  --input "Say this is a test"

Prompts longos não precisam de escape. Flags de entrada JSON leem de um arquivo com @path:

openai responses create --model gpt-5.5 --input @prompt.txt

Se você canalizar JSON ou YAML de uma fonte não confiável, defina OPENAI_UNTRUSTED_STDIN=1 para que essa entrada não possa acionar leituras de arquivos locais.

Faça upload e busque arquivos

openai files upload report.txt --purpose user_data
openai files get file-example
openai files download file-example --output downloaded-report.txt

Execute um batch

Coloque uma requisição por linha em requests.jsonl, cada uma com um custom_id único, e então:

openai files upload requests.jsonl --purpose batch
openai batches create --input-file-id file-example \
  --endpoint /v1/responses --completion-window 24h
openai batches wait batch_example --output-dir ./results

batches wait faz polling até o batch terminar e salva os arquivos de resultado, o que elimina o loop de polling que você escreveria de outra forma. O guia de batch do projeto lista os limites atuais como 50.000 requisições e 200 MB por arquivo de entrada, com uma janela de conclusão de 24h. O preço de batch difere das chamadas síncronas; consulte nossa análise de preços da API OpenAI antes de enfileirar um job grande.

Conte tokens localmente, sem chave

O comando tokenizer roda totalmente offline: sem credenciais, sem rede, sem entrada salva.

A codificação padrão é o200k_base, e openai tokenizer encodings lista as outras (cl100k_base, além de duas legadas). O help é honesto sobre os limites: uma contagem de texto simples exclui a estrutura da requisição e entradas multimodais, então não é um valor de cobrança. Para uma contagem no lado do servidor, use openai responses input-tokens count.

Obtenha saída que um script consegue analisar

A saída padrão é texto legível, mesmo quando canalizada. Peça dados explicitamente:

openai models list --format jsonl | jq '.id'
openai files list --format json > files.json
openai files get file-example --transform filename --raw-output

--format aceita auto, text, json, jsonl, yaml, explore (um visualizador JSON interativo) e pretty. --transform extrai campos com a sintaxe GJSON, e o jq lida com qualquer coisa mais elaborada. Sempre verifique o status de saída antes de confiar em um arquivo redirecionado: uma requisição com falha pode deixar um arquivo parcial para trás.

Quando uma chamada se comporta mal, --debug adiciona o tempo HTTP por tentativa; limpe seus logs antes de compartilhá-los. Se você está recebendo 429s, nosso guia de limites de taxa da OpenAI explica os níveis.

OpenAI CLI vs Codex CLI vs o antigo comando openai

Três ferramentas compartilham um fornecedor e duas compartilham um nome. Esta é a versão curta:

Execute openai codex e o OpenAI CLI imprime os comandos de instalação do Codex, observando que é uma ferramenta separada com seu próprio login. Nosso guia do Codex CLI cobre o lado do agente, e o código-fonte fica em github.com/openai/codex.

Fique atento ao conflito de PATH

O pacote Python openai também instala um binário chamado openai. Se você já executou pip install openai, pode ter dois:

Neste Mac, o do Python reporta openai 2.30.0 e oferece os subcomandos api, tools, migrate e grit; o do Go reporta openai version 1.44.1. Qualquer diretório que vier primeiro no seu PATH vence. Execute which -a openai e openai --version depois de instalar. Se a saída disser openai version 1.44.1 (ou mais recente), você tem o correto. Se ela imprimir apenas um número de versão, como openai 2.30.0, reordene seu PATH ou chame o novo binário pelo caminho completo.

Onde o Apidog CLI se encaixa ao lado do OpenAI CLI

O OpenAI CLI faz chamadas para a OpenAI. Ele não conhece a sua própria API: os endpoints que sua aplicação expõe sobre a OpenAI, os ambientes para os quais você faz deploy, ou as asserções que provam que um release não quebrou nada. Essa é uma função diferente, e é aí que entra o Apidog CLI. Você não escolhe um em vez do outro; a maioria das equipes que entrega um recurso de IA quer ambos.

Melhor ainda, deixe seu agente de programação executar os dois. Configure o Apidog CLI uma vez:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Então dê ao seu agente um único [REDACTED PROMPT]
Use the openai CLI to confirm my key works with one responses create call on gpt-5.5.
Then import ./openapi.yaml into Apidog project , create a test case for
POST /v1/summarize that asserts a 200 and a non-empty "summary" field, run it
against the staging environment and summarize any failures.

O agente verifica a chave com `openai`, então trabalha através do Apidog CLI. Ele lê o schema antes de escrever qualquer payload, valida o arquivo e só então cria e executa o caso:

bash
apidog import --project --format openapi --file ./openapi.yaml
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project --file case.json
apidog run --test-case --project -e -r cli,json

Dois detalhes de `apidog test-case create --help` economizam uma ida e volta: o caso precisa de um `categoryId` válido (liste-os com `apidog test-case category --project <id>`), e os payloads devem vir do `cli-schema`, nunca da memória. A mesma linha de `apidog run` com `-r junit` entra no CI, como mostra nosso [guia do Apidog CLI para CI/CD](https://apidog.com/pt/blog/apidog-cli-ci-cd-pipeline?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation). Se o Codex é seu agente, comece com [Apidog CLI no Codex](https://apidog.com/pt/blog/apidog-cli-in-codex?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).

O plano Gratuito do Apidog cobre até 4 usuários, então uma equipe pequena pode experimentar isso sem uma decisão de compra.

## FAQ

**O OpenAI CLI é gratuito?** A ferramenta é gratuita e de código aberto sob Apache 2.0. As chamadas de API que ela faz são cobradas na sua conta OpenAI às taxas normais da API. Comandos locais como `openai tokenizer` e toda página `--help` não custam nada e não precisam de chave.

**O OpenAI CLI é o mesmo que o Codex CLI?** Não. O `openai` envia requisições diretas à API, uma por comando. O `codex` é um agente de programação que lê e edita seu projeto e executa comandos. Eles são instalados separadamente e se autenticam separadamente.

**Como instalo o OpenAI CLI em um Mac?** Execute `brew install openai/tools/openai`, ou baixe o zip `macos_arm64` (Apple Silicon) ou `macos_amd64` (Intel) do GitHub Releases e coloque o binário no seu PATH. Depois execute `openai --version` para confirmar que você não está acionando o comando Python `openai` mais antigo.

**O OpenAI CLI funciona em scripts de shell e CI?** Sim, esse é seu principal objetivo de design. Use `--format json` ou `jsonl` para saída analisável, verifique o status de saída, mantenha a chave em `OPENAI_API_KEY` a partir do seu gerenciador de segredos, e defina `OPENAI_CLI_NO_AUTO_UPDATE=1` para manter a versão fixada.

**Quando o OpenAI CLI foi lançado?** A versão 1.0.0 foi publicada no GitHub em 5 de maio de 2026. Em 28 de outubro de 2026, a versão mais recente é a 1.44.1, de 27 de outubro.