CLI da OpenAI

Interaja com a API da OpenAI diretamente no terminal usando a ferramenta de linha de comando openai.

Instalação

Instale a CLI com o Homebrew:

brew install openai/tools/openai

Ou instale com o Go 1.25 ou posterior:

go install 'github.com/openai/openai-cli/cmd/openai@latest'

Versões anteriores do SDK para Python também instalavam uma versão antiga do comando openai. Se você já tinha esse pacote instalado e o comando disponível é diferente do descrito neste guia, o shell pode ainda estar encontrando o binário antigo. Isso não afeta novas instalações da CLI.

Explore os comandos

Execute openai explore no terminal para consultar os comandos disponíveis antes de configurar uma chave de API. Digite uma tarefa, como count tokens offline, para encontrar o comando openai tokenizer count. Use as teclas de seta para destacar um resultado. Pressione Enter para selecioná-lo ou Escape para cancelar.

O Explore exibe o comando selecionado sem executá-lo. Com a integração com o shell, você pode editar esse comando no próprio prompt. Execute openai explore --help para consultar a lista de shells compatíveis e os atalhos de teclado.

Autenticação

A CLI lê sua chave de API da variável OPENAI_API_KEY:

Comando:

export OPENAI_API_KEY="sk-..."

Se você ainda não tem uma chave de API, crie uma no painel.

Para endpoints da API de administração, defina OPENAI_ADMIN_KEY em vez da chave padrão. A camada do SDK escolhe entre a chave de administrador e a chave de API padrão de acordo com o endpoint chamado.

Para usar outro host da API, defina OPENAI_BASE_URL.

Casos de uso

Use a CLI para tarefas que você faria no terminal:

• Gere artefatos locais, como imagens ou arquivos de áudio com fala sintetizada.
• Extraia dados estruturados em JSONL para processá-los depois no shell.
• Use Responses na nuvem com arquivos, o recurso Uso do computador e informações atualizadas da Web.
• Crie projetos e chaves de API com as APIs de administração.

Use a CLI diretamente para requisições pontuais no terminal ou em scripts quando os agentes precisarem repetir operações em lote com arquivos e artefatos gerados.

Quando usar a CLI ou subagentes no Codex

Use a CLI para operações de API que você quer inspecionar e executar novamente, como extrair dados em lote, transformar arquivos, gerar artefatos ou escolher explicitamente um modelo. Use subagentes quando a tarefa ainda exigir discernimento, como ao explorar código, comparar hipóteses, depurar problemas ou revisar alterações.

Opções globais

Estas opções podem ser usadas em todos os comandos:

Este guia se concentra nas formas de usar a CLI. Para conferir os argumentos e as estruturas de resposta atuais de qualquer família de APIs, consulte a referência da API.

Você também pode alterar a URL base para direcionar a CLI a outro endpoint compatível, por exemplo, o de uma implantação que ofereça um conjunto diferente de modelos ou apenas parte dos recursos da API.

Responses

Use a API Responses para gerar texto, extrair dados estruturados, pesquisar na Web, interpretar arquivos e executar repetidamente scripts de processamento em lote criados pelo Codex.

Envie sua primeira requisição

Comando:

1
2
3openai responses create \
  --model gpt-6-astra \
  --input "Say hello in one sentence."

Saída:

123456789101112131415161718192021222324{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5-...",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6,
    "total_tokens": 18
  },
  "...": "additional response fields omitted"
}

Por padrão, a CLI exibe o objeto de resposta completo da API. Os exemplos desta página mostram campos representativos, como id, status, model, output e usage, e omitem os demais.

Na saída da API Responses, itens de outros tipos, como os de raciocínio, podem aparecer antes da mensagem do assistente. Para obter o texto do assistente, selecione o item de mensagem pelo tipo em vez de presumir que ele sempre estará em output[0]:

--transform 'output.#(type=="message").content.0.text'

Adicione um arquivo local ao prompt

Para incluir um arquivo local, monte o prompt na própria linha de comando usando substituição de comando:

1
2
3
4
5
6
7
8
9openai responses create \
  --model gpt-6-astra \
  --input "Summarize this note in one sentence.

<note>
$(cat ./note.md)
</note>" \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text'

Saída:

The note says the launch checklist is ready except for final support ownership.

Como passar o corpo da requisição

Use opções de linha de comando para entradas escalares curtas. Para prompts com várias linhas, ferramentas, arquivos ou corpos de requisição com estruturas aninhadas, use um here-document em YAML. Ele pode conter os mesmos campos de requisição que você passaria pelas opções de linha de comando.

Tenha cuidado com strings que se parecem com YAML, especialmente prompts que contêm : ou {}. Ao receber esses valores pelas opções de linha de comando, o analisador gerado pode interpretá-los como YAML estruturado em vez de texto simples. Se o prompt começar a se parecer com uma configuração, escreva-o abaixo de input: | no corpo da requisição em YAML:

Comando:

1
2
3
4
5
6
7
8
9
10
11
12
13openai responses create \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text' <<'YAML'
model: gpt-5.5
instructions: Return exactly one sentence.
max_output_tokens: 120
input: |
  Summarize this release note in one sentence.

  <release_note>
  Fixed the image generation example and added CLI installation guidance.
  </release_note>
YAML

Saída:

The release note updates the CLI docs with corrected image generation and installation guidance.

Quando você precisar montar o próprio prompt no shell, crie o corpo da requisição em YAML e passe-o ao comando por um pipe:

1
2
3
4
5
6
7
8
9
10{
  printf 'input: |\n'
  printf '  Summarize this note in one sentence.\n\n'
  printf '  <note>\n'
  sed 's/^/  /' ./note.md
  printf '  </note>\n'
} | openai responses create \
  --model gpt-6-astra \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text'

Grave dados estruturados em JSON

Use saídas estruturadas quando os scripts das etapas seguintes precisarem de JSON com estrutura estável. Salve em disco os schemas que pretende reutilizar:

Salve como schema.json:

1234567891011121314{
  "type": "json_schema",
  "name": "fact",
  "strict": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "person": { "type": "string" },
      "topic": { "type": "string" }
    },
    "required": ["person", "topic"]
  }
}

Comando:

1
2
3
4
5
6
7openai responses create \
  --model gpt-6-astra \
  --instructions "Extract the person and topic from the input." \
  --input "Ada Lovelace wrote notes about the Analytical Engine." \
  --text.format "$(cat ./schema.json)" \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text'

Saída:

{ "person": "Ada Lovelace", "topic": "notes about the Analytical Engine" }

Grave registros estruturados em JSONL

Quando uma única entrada puder gerar vários registros, peça ao modelo que retorne um array e converta os elementos em registros JSONL. Assim, as próximas etapas do shell poderão processar um registro por linha:

Salve como records-schema.json:

12345678910111213141516171819202122232425{
  "type": "json_schema",
  "name": "items",
  "strict": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "title": { "type": "string" },
            "summary": { "type": "string" },
            "evidence": { "type": "string" }
          },
          "required": ["title", "summary", "evidence"]
        }
      }
    },
    "required": ["items"]
  }
}

Comando:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20: > records.jsonl

for file in notes/*.md; do
  extracted="$(
    openai responses create \
      --model gpt-5.5 \
      --text.format "$(cat ./records-schema.json)" \
      --raw-output \
      --transform 'output.#(type=="message").content.0.text' <<YAML
input: |
  <note path="$file">
$(sed 's/^/  /' "$file")
  </note>
YAML
  )"

  jq -r --arg source "$file" \
    '.items[]? + {source: $source} | @json' \
    <<<"$extracted" >> records.jsonl
done

Isso mantém a resposta do modelo estruturada e gera um objeto JSON por linha para as próximas etapas do shell.

Pesquisa na Web

A API Responses pode chamar ferramentas hospedadas a partir do mesmo corpo de requisição em YAML:

Comando:

1
2
3
4
5
6
7
8
9
10openai responses create \
  --model gpt-6-astra \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text' <<'YAML'
tools:
  - type: web_search
input: |
  Research the latest material news for AAPL.
  Return three concise bullets and cite sources in the text.
YAML

Saída:

- Apple announced ...
- Analysts highlighted ...
- The company said ...

Arquivos de entrada

Para usar arquivos enviados à API, como PDFs, primeiro crie o arquivo na API, obtenha seu ID e passe-o como input_file.file_id:

Comando:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20FILE_ID=$(
  openai files create \
    --file ./brief.pdf \
    --purpose user_data \
    --format yaml \
    --transform id
)

openai responses create \
  --model gpt-5.5 \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text' <<YAML
input:
  - role: user
    content:
      - type: input_text
        text: Summarize this brief and list three risks.
      - type: input_file
        file_id: ${FILE_ID}
YAML

Saída:

- The brief proposes ...
- Risks: migration timing, unclear rollback criteria, and unresolved support ownership.

Nas versões mais recentes da CLI gerada, os arquivos locais indicados pelas opções de linha de comando são enviados como partes de uma requisição multipart, com o nome do arquivo e o tipo de conteúdo nos metadados. Se o comando de envio de um arquivo local falhar com um erro de tipo UploadFile, atualize a CLI e tente novamente.

Imagens

Gere uma imagem

Gere uma imagem, extraia os dados em base64 e decodifique-os para salvar a imagem em um arquivo comum:

Comando:

1
2
3
4
5
6openai images generate \
  --model gpt-image-2 \
  --prompt "A simple product-style render of a translucent green cube on a neutral background." \
  --format yaml \
  --transform 'data.0.b64_json' | base64 --decode > hero.png
printf 'wrote hero.png\n'

Saída:

wrote hero.png

Os comandos de imagem ainda não oferecem suporte nativo a --output. Por isso, na geração de imagens, você precisa extrair b64_json e decodificar os dados por conta própria.

Para gpt-image-2, omita --input-fidelity, pois as imagens de entrada são sempre processadas com alta fidelidade. O suporte a fundos transparentes está disponível em prévia. Use --background transparent com png (o padrão) ou webp. O formato jpeg não é compatível com fundos transparentes. O modelo também aceita uma variedade maior de valores para --size do que os modelos GPT Image anteriores, desde que a resolução solicitada atenda às restrições de tamanho da API de imagens.

Edite uma imagem

Após a conclusão bem-sucedida da requisição de edição, extraia os dados em base64 da mesma forma:

Comando:

1
2
3
4
5
6
7openai images edit \
  --model gpt-image-2 \
  --image ./hero.png \
  --prompt "Turn the cube bright green." \
  --format yaml \
  --transform 'data.0.b64_json' | base64 --decode > hero-edited.png
printf 'wrote hero-edited.png\n'

Saída:

wrote hero-edited.png

Se o envio de uma imagem local para edição falhar com um erro de tipo UploadFile, atualize a CLI e tente novamente.

Síntese de fala

Crie um arquivo MP3 localmente com a API de síntese de fala:

Comando:

1
2
3
4
5openai audio:speech create \
  --model gpt-4o-mini-tts \
  --voice marin \
  --input "The OpenAI CLI can call the API from ordinary shell scripts." \
  --output speech.mp3

Saída:

Wrote output to: speech.mp3

Reproduza o arquivo com uma ferramenta de áudio disponível no seu computador. No macOS:

afplay speech.mp3

Use --instructions para orientar a maneira de falar e --input para indicar o texto a ser falado. Nas instruções, você pode especificar o ritmo, a energia, o tom acolhedor, o grau de formalidade, a ênfase ou o público a que a fala se destina:

1
2
3
4
5
6openai audio:speech create \
  --model gpt-4o-mini-tts \
  --voice marin \
  --instructions "Whisper very quickly, like a hurried stage cue, while staying clear and intelligible." \
  --input "The launch checklist is ready. Please send final feedback by Friday at noon." \
  --output reminder.mp3

Transcrição

Gere a transcrição em texto simples para usá-la em pipelines do shell:

Comando:

1
2
3
4
5openai audio:transcriptions create \
  --model gpt-transcribe \
  --file ./speech.mp3 \
  --transform text \
  --raw-output

Saída:

The OpenAI CLI can call the API from ordinary shell scripts.

O exemplo acima usa o modelo recomendado para transcrição de arquivos. Os exemplos a seguir continuam disponíveis para integrações existentes com necessidades específicas:

Para obter marcações de tempo por palavra, solicite o formato detalhado de transcrição:

Comando:

1
2
3
4
5
6openai audio:transcriptions create \
  --model whisper-1 \
  --file ./speech.mp3 \
  --response-format verbose_json \
  --timestamp-granularity word \
  --format json

Saída:

1234567891011{
  "task": "transcribe",
  "language": "english",
  "duration": 6,
  "text": "The OpenAI CLI can call the API from ordinary shell scripts.",
  "words": [
    { "word": "The", "start": 0, "end": 0.42 },
    { "word": "OpenAI", "start": 0.42, "end": 1.22 }
  ],
  "...": "additional response fields omitted"
}

Para identificar quem fala em cada segmento, use o modelo de diarização e solicite diarized_json:

Comando:

1
2
3
4
5openai audio:transcriptions create \
  --model gpt-4o-transcribe-diarize \
  --file ./speech.mp3 \
  --response-format diarized_json \
  --format json

Saída:

1234567891011121314{
  "text": "The OpenAI CLI can call the API from ordinary shell scripts.",
  "segments": [
    {
      "type": "transcript.text.segment",
      "id": "seg_0",
      "start": 0.05,
      "end": 5.25,
      "text": " The OpenAI CLI can call the API from ordinary shell scripts.",
      "speaker": "A"
    }
  ],
  "...": "additional response fields omitted"
}

O modelo whisper-1 aceita json, text, srt, verbose_json e vtt. O formato diarized_json inclui o campo segments[].speaker. Se você usar o mesmo modelo de diarização com o formato json simples, a resposta conterá o texto da transcrição sem identificar quem fala.

APIs de administração

Use as APIs de administração para gerenciar a organização, provisionar credenciais, atender a requisitos de conformidade e monitorar o uso. Defina OPENAI_ADMIN_KEY e execute os comandos gerados no formato admin:organization:*.

Para provisionar uma nova credencial de máquina, crie um projeto, crie uma conta de serviço nesse projeto e use a chave de API retornada.

Crie um projeto, uma conta de serviço e uma chave de API

Ao criar a conta de serviço nesse projeto, você recebe a chave de API completa da conta.

Comando:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15# Create the project that will own this app or agent and save the response.
openai admin:organization:projects create \
  --name "automation project" \
  --format json > project.json
PROJECT_ID="$(jq -r '.id' project.json)"

# Create a service account inside the project and save the full response.
openai admin:organization:projects:service-accounts create \
  --project-id "$PROJECT_ID" \
  --name "automation bot" \
  --format json > service-account.json

# Extract the returned API key into an env file for the workload to use.
jq -r '.api_key.value | "OPENAI_API_KEY=\(.)"' \
  service-account.json > .env

Saída:

12345678910{
  "object": "organization.project.service_account",
  "id": "svc_acct_...",
  "name": "automation bot",
  "role": "member",
  "api_key": {
    "id": "key_...",
    "value": "sk-..."
  }
}

O exemplo grava a resposta de criação do projeto em project.json, extrai o ID do projeto para usá-lo no comando seguinte, grava a resposta de criação da conta de serviço em service-account.json e salva a credencial retornada em .env como OPENAI_API_KEY=.... Trate os dois arquivos JSON como segredos e adicione project.json, service-account.json e .env ao .gitignore antes de usar esse procedimento em um repositório.

Para conhecer os demais recursos, consulte o guia das APIs de administração e a referência atual da API de administração. Avalie se o solicitante é confiável antes de conceder acesso às chaves de administrador.