OpenAI CLI

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 de Python também instalavam um comando openai legado. Se você já tinha esse pacote instalado e o comando exibido não corresponde ao deste guia, seu shell pode ainda estar encontrando o binário antigo. Novas instalações da CLI não são afetadas.

Autenticação

A CLI lê sua chave de API de 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 disso. A camada do SDK seleciona a chave de administração ou a chave de API padrão com base no endpoint chamado.

Para apontar para outro host de API, defina OPENAI_BASE_URL.

Casos de uso

Use a CLI quando fizer sentido realizar o trabalho no terminal:

• Gere artefatos locais, como imagens ou áudio de fala.
• Extraia dados estruturados para JSONL e use-os nas etapas seguintes no shell.
• Use Responses com arquivos, uso do computador e contexto atualizado da Web na nuvem.
• Crie projetos e chaves de API com as APIs de administração.

Use a CLI diretamente para solicitações pontuais no terminal ou em scripts quando os agentes precisarem repetir o processamento em lote de arquivos e artefatos gerados.

CLI ou subagentes no Codex

Use a CLI para tarefas de API repetíveis que você queira inspecionar e executar novamente, como extração em lote, transformação de arquivos, geração de artefatos ou seleção deliberada de modelos. Use subagentes quando o trabalho ainda exigir discernimento, como explorar código, comparar hipóteses, depurar ou revisar alterações.

Flags globais

Estas opções funcionam em todos os comandos:

Este guia se concentra nos padrões de uso da CLI. Para consultar os argumentos e formatos de resposta mais recentes de qualquer família de APIs, use a referência da API atualizada.

Você também pode alterar a URL base quando precisar apontar a CLI para outro endpoint compatível, como uma implantação que ofereça suporte a um conjunto diferente de modelos ou apenas a parte das funcionalidades da API.

Responses

Use Responses para geração de texto, extração estruturada, pesquisa na Web, compreensão de arquivos e scripts de processamento em lote criados pelo Codex que possam ser executados repetidamente.

Envie sua primeira solicitaçã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 completo de resposta da API. Os exemplos desta página mantêm campos representativos, como id, status, model, output e usage, e omitem os demais.

A saída de Responses pode incluir itens que não são mensagens, como itens de raciocínio, antes da mensagem do assistente. Quando precisar do texto do assistente, selecione o item de mensagem pelo tipo, em vez de presumir que ele sempre está em output[0]:

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

Adicione um arquivo local ao prompt

Para um arquivo local simples, monte o prompt diretamente na linha de comando usando substituição de comandos:

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 corpos de solicitação

Use flags para entradas escalares curtas. Use um heredoc YAML para prompts com várias linhas, ferramentas, arquivos ou corpos de solicitação com estruturas aninhadas. O heredoc pode conter os mesmos campos de solicitação que você passaria como flags.

Tenha cuidado com valores de string que se pareçam com YAML, especialmente prompts que contenham : ou {}. Nas flags, o analisador gerado pode interpretar esses valores como YAML estruturado em vez de texto simples. Se um prompt começar a parecer uma configuração, coloque-o sob input: | em um corpo 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 o próprio prompt precisar ser montado no shell, crie um corpo 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 esquemas reutilizáveis em disco:

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 entrada puder gerar vários registros, peça ao modelo um array e converta-o em JSONL para que as etapas seguintes no shell possam 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 etapas seguintes no 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 arquivos enviados, como PDFs, primeiro crie o arquivo, capture seu ID e passe esse ID 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.

As versões geradas mais recentes enviam os arquivos locais indicados pelas flags como partes de arquivo multipart, com metadados de nome de arquivo e tipo de conteúdo. Se um comando de envio de arquivo local falhar com um erro de tipo UploadFile, atualize a CLI e tente novamente.

Imagens

Gere uma imagem

Gere uma imagem, extraia o conteúdo em base64 e decodifique-o em um arquivo de imagem 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

Limitação atual: os comandos de imagem ainda não têm suporte nativo a --output, então a geração de imagens ainda exige que você extraia b64_json e faça a decodificação por conta própria.

Para gpt-image-2, omita --input-fidelity; as entradas de imagem são sempre processadas com alta fidelidade. Fundos transparentes estão disponíveis em versão 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 de --size do que os modelos GPT Image anteriores, desde que a resolução solicitada atenda às restrições de tamanho da API Image.

Edite uma imagem

A edição de imagens usa o mesmo padrão de extração de base64 depois que a requisição de edição é concluída com sucesso:

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.

Fala

Crie um MP3 localmente com a API 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 qualquer ferramenta de áudio local disponível na sua máquina. No macOS:

afplay speech.mp3

Use --instructions para definir o estilo da fala e --input para o texto que deve ser falado. As instruções funcionam bem para orientações sobre ritmo, energia, tom acolhedor, formalidade, ênfase ou público:

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

Exiba a transcrição em texto simples para uso em pipelines de shell:

Comando:

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

Saída:

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

Use o formato de resposta adequado ao artefato de que você precisa:

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 obter uma saída com identificação de falantes, 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"
}

whisper-1 oferece suporte a json, text, srt, verbose_json e vtt. diarized_json é o formato que inclui segments[].speaker; com o mesmo modelo de diarização e o formato json simples, a resposta contém o texto da transcrição, mas não a identificação dos falantes.

APIs de administração

Use as APIs de administração em fluxos de trabalho de gerenciamento da organização, provisionamento de credenciais, conformidade e monitoramento de uso. Defina OPENAI_ADMIN_KEY e, em seguida, execute os comandos gerados 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

A criação de uma conta de serviço nesse projeto retorna uma chave de API sem mascaramento para a conta de serviço.

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-..."
  }
}

Isso grava a resposta do projeto em project.json, extrai seu ID para o próximo comando, grava a resposta da conta de serviço em service-account.json e grava a credencial retornada em .env como OPENAI_API_KEY=.... Trate ambos os arquivos JSON como segredos e adicione project.json, service-account.json e .env ao .gitignore antes de usar esse padrão em um repositório.

Para conhecer as demais funcionalidades, consulte o guia das APIs de administração e a referência atual da API de administração. Tenha cuidado ao conceder acesso a chaves de administração a agentes cuja confiabilidade não foi verificada.