CLI OpenAI

Interagissez avec l’API OpenAI directement depuis votre terminal grâce à l’outil en ligne de commande openai.

Installation

Installez la CLI avec Homebrew :

brew install openai/tools/openai

Ou installez-la avec Go 1.25 ou une version ultérieure :

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

Les anciennes versions du SDK Python installaient également une ancienne commande openai. Si ce package était déjà installé et que la commande affichée ne correspond pas à ce guide, votre shell utilise peut-être encore l’ancien binaire. Les nouvelles installations de la CLI ne sont pas concernées.

Authentification

La CLI lit votre clé API dans OPENAI_API_KEY :

Commande :

export OPENAI_API_KEY="sk-..."

Si vous n’avez pas encore de clé API, créez-en une dans le tableau de bord.

Pour les points de terminaison de l’API d’administration, définissez plutôt OPENAI_ADMIN_KEY. La couche SDK sélectionne la clé d’administration ou la clé API par défaut en fonction du point de terminaison appelé.

Pour utiliser un autre hôte API, définissez OPENAI_BASE_URL.

Cas d’utilisation

Utilisez la CLI pour les tâches qui se prêtent naturellement au terminal :

• Générez des fichiers locaux, comme des images ou des fichiers de synthèse vocale.
• Extrayez des données structurées au format JSONL pour les étapes suivantes dans le shell.
• Utilisez Responses dans le cloud avec des fichiers, l’utilisation de l’ordinateur et un contexte web à jour.
• Créez des projets et des clés API avec les API d’administration.

Utilisez-la directement pour des requêtes ponctuelles dans le terminal, ou depuis des scripts lorsque les agents doivent effectuer des traitements par lots reproductibles sur des fichiers et des artefacts générés.

CLI ou sous-agents pour Codex

Utilisez la CLI pour les opérations API reproductibles que vous souhaitez examiner et relancer, comme l’extraction par lots, la transformation de fichiers, la génération d’artefacts ou le choix explicite d’un modèle. Utilisez des sous-agents lorsque le travail nécessite encore du discernement, par exemple pour explorer du code, comparer des hypothèses, déboguer ou réviser des modifications.

Options globales

Ces options sont communes aux différentes commandes :

Ce guide présente les usages de la CLI. Pour connaître les derniers arguments et structures de réponse de chaque famille d’API, consultez la référence de l’API en ligne.

Vous pouvez également modifier l’URL de base pour diriger la CLI vers un autre point de terminaison compatible, par exemple un déploiement qui prend en charge un ensemble de modèles différent ou seulement une partie des fonctionnalités de l’API.

Responses

Utilisez Responses pour la génération de texte, l’extraction structurée, la recherche web, la compréhension de fichiers et les scripts de traitement par lots reproductibles écrits par Codex.

Envoyez votre première requête

Commande :

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

Sortie :

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

Par défaut, la CLI affiche l’objet de réponse API complet. Les exemples de cette page ne conservent que des champs représentatifs tels que id, status, model, output et usage, et omettent les autres.

La sortie de Responses peut contenir des éléments autres que des messages, comme des éléments de raisonnement, avant le message de l’assistant. Lorsque vous avez besoin du texte de l’assistant, sélectionnez l’élément de type message plutôt que de supposer qu’il se trouve toujours dans output[0] :

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

Ajoutez un fichier local au prompt

Pour un fichier local simple, construisez le prompt directement dans la ligne de commande à l’aide de la substitution de commande :

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'

Sortie :

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

Transmettez des corps de requête

Utilisez des options pour les entrées scalaires courtes. Utilisez un heredoc YAML pour les prompts sur plusieurs lignes, les outils, les fichiers ou les corps de requête imbriqués. Le heredoc peut contenir les mêmes champs de requête que ceux que vous transmettriez sous forme d’options.

Faites attention aux chaînes de caractères qui ressemblent à du YAML, en particulier aux prompts contenant : ou {}. Lorsqu’elles sont transmises sous forme d’options, l’analyseur généré peut interpréter ces valeurs comme du YAML structuré plutôt que comme du texte brut. Si un prompt commence à ressembler à de la configuration, placez-le plutôt sous input: | dans un corps YAML :

Commande :

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

Sortie :

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

Lorsque le prompt lui-même doit être assemblé dans le shell, construisez un corps YAML et transmettez-le à la commande à l’aide d’un 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'

Écrivez des données structurées au format JSON

Utilisez les sorties structurées lorsque les scripts en aval ont besoin de JSON à la structure stable. Enregistrez les schémas réutilisables sur disque :

Enregistrez sous 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"]
  }
}

Commande :

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'

Sortie :

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

Écrivez des enregistrements structurés au format JSONL

Lorsqu’une entrée peut produire plusieurs enregistrements, demandez au modèle un tableau et convertissez-le en JSONL pour que les étapes suivantes du script shell puissent traiter un enregistrement par ligne :

Enregistrez sous 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"]
  }
}

Commande :

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

La réponse du modèle reste ainsi structurée, avec un objet JSON par ligne pour les étapes suivantes du script shell.

Recherche web

Responses peut appeler des outils hébergés à partir du même corps de requête YAML :

Commande :

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

Sortie :

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

Fichiers en entrée

Pour les fichiers téléversés, comme les PDF, créez d’abord le fichier, récupérez son identifiant et transmettez-le dans input_file.file_id :

Commande :

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

Sortie :

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

Les versions générées récentes envoient les fichiers locaux indiqués par les options sous forme de parties de fichier multipart, avec des métadonnées précisant le nom du fichier et le type de contenu. Si une commande de téléversement d’un fichier local échoue avec une erreur de type UploadFile, mettez à jour la CLI et réessayez.

Images

Générez une image

Générez une image, extrayez les données en base64 et décodez-les pour obtenir un fichier image classique :

Commande :

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'

Sortie :

wrote hero.png

Limitation actuelle : les commandes d’image ne prennent pas encore en charge --output de manière native. La génération d’images nécessite donc toujours d’extraire b64_json et de le décoder vous-même.

Pour gpt-image-2, omettez --input-fidelity ; les images en entrée sont toujours traitées en haute fidélité. Les arrière-plans transparents sont disponibles en préversion ; utilisez --background transparent avec png (le format par défaut) ou webp. Le format jpeg n’est pas pris en charge avec les arrière-plans transparents. Le modèle prend également en charge un éventail de valeurs --size plus large que les modèles GPT Image précédents, à condition que la résolution demandée respecte les contraintes de taille de l’API Image.

Modifiez une image

La modification d’images utilise la même méthode d’extraction des données en base64 une fois la requête de modification réussie :

Commande :

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'

Sortie :

wrote hero-edited.png

Si le téléversement d’une image locale à modifier échoue avec une erreur de type UploadFile, mettez à jour la CLI et réessayez.

Synthèse vocale

Créez un fichier MP3 en local avec l’API de synthèse vocale :

Commande :

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

Sortie :

Wrote output to: speech.mp3

Écoutez-le avec n’importe quel outil audio disponible sur votre machine. Sur macOS :

afplay speech.mp3

Utilisez --instructions pour définir la manière de s’exprimer et --input pour le texte à prononcer. Les instructions conviennent bien aux indications de rythme, d’énergie, de chaleur, de registre, d’accentuation ou de public visé :

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

Transcription

Affichez la transcription en texte brut pour les pipelines shell :

Commande :

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

Sortie :

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

Utilisez le format de réponse correspondant au résultat dont vous avez besoin :

Pour obtenir les horodatages de chaque mot, demandez le format de transcription détaillé :

Commande :

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

Sortie :

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

Pour obtenir une sortie qui identifie les locuteurs, utilisez le modèle de diarisation et demandez le format diarized_json :

Commande :

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

Sortie :

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 prend en charge les formats json, text, srt, verbose_json et vtt. Le format diarized_json contient segments[].speaker ; avec le même modèle de diarisation et le format json simple, la réponse contient le texte de la transcription, mais pas les identifiants des locuteurs.

API d’administration

Utilisez les API d’administration pour vos workflows de gestion des organisations, de provisionnement des identifiants d’authentification, de conformité et de suivi de l’utilisation. Définissez OPENAI_ADMIN_KEY, puis exécutez les commandes générées admin:organization:*.

Pour provisionner un nouvel identifiant d’authentification machine, créez un projet, créez un compte de service dans ce projet, puis utilisez la clé API renvoyée.

Créez un projet, un compte de service et une clé API

La création d’un compte de service dans ce projet renvoie une clé API non masquée pour ce compte.

Commande :

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

Sortie :

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

Ces commandes enregistrent la réponse du projet dans project.json, en extraient l’ID pour la commande suivante, enregistrent la réponse du compte de service dans service-account.json, puis écrivent l’identifiant d’authentification renvoyé dans .env sous la forme OPENAI_API_KEY=.... Traitez les deux fichiers JSON comme des secrets et ajoutez project.json, service-account.json et .env à .gitignore avant d’utiliser cette méthode dans un dépôt.

Pour découvrir les autres fonctionnalités, consultez le guide des API d’administration et la référence de l’API d’administration à jour. Faites preuve de prudence avant de donner accès aux clés d’administration à des acteurs dont la fiabilité n’a pas été vérifiée.