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.
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:
- 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
openaino seu PATH. - Homebrew.
brew install openai/tools/openai
- 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:
| Configuração | Flag | Variável de ambiente | Use para |
|---|---|---|---|
| Chave de API | --api-key |
OPENAI_API_KEY |
Toda chamada normal à API |
| Chave de administrador | --admin-api-key |
OPENAI_ADMIN_KEY |
openai admin ... (uso, projetos); uma chave de projeto não pode substituí-la |
| URL base | --base-url |
OPENAI_BASE_URL |
Apontar o CLI para outro host ou um gateway |
| Certificado e chave mTLS | --mtls-client-cert-file, --mtls-client-key-file |
OPENAI_MTLS_CLIENT_CERT_FILE, OPENAI_MTLS_CLIENT_KEY_FILE |
mTLS mútuo, que exige uma URL base HTTPS explícita |
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:
| OpenAI CLI | Codex CLI | openai Python legado |
|
|---|---|---|---|
| Comando | openai |
codex |
openai |
| O que é | Um cliente para a API REST | Um agente de programação que lê, edita e executa código no seu projeto | Um CLI incluído no pacote Python openai |
| Instalação | Binário, Homebrew ou Go | npm install -g @openai/codex ou brew install --cask codex |
pip install openai |
| Autenticação | OPENAI_API_KEY |
Gerencia seu próprio login | Chave de API |
| Use quando | Você quer uma chamada específica à API, ou etapas de API em um script | Você quer que um agente implemente ou depure uma mudança | Você mantém scripts mais antigos construídos sobre ele |
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 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 <id>, 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:
apidog import --project <id> --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 <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> -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. Se o Codex é seu agente, comece com Apidog CLI no Codex.
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.