OpenAI CLI

Appelez l’API OpenAI directement depuis votre terminal avec l’outil en ligne de commande openai.

Installation

Installez la CLI avec Homebrew :

brew install openai/tools/openai

Vous pouvez aussi l’installer 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 aussi une commande openai. Si ce paquet était déjà installé et que la commande dont vous disposez ne correspond pas à celle de ce guide, votre shell utilise peut-être encore l’ancien exécutable. Les nouvelles installations de la CLI ne sont pas concernées.

Explorez les commandes

Exécutez openai explore dans votre terminal pour parcourir les commandes avant de configurer une clé API. Décrivez la tâche à accomplir. Par exemple, saisissez count tokens offline pour trouver openai tokenizer count. Utilisez les touches fléchées pour mettre un résultat en surbrillance. Appuyez sur Entrée pour le sélectionner ou sur Échap pour annuler.

Explore affiche la commande sélectionnée sans l’exécuter. Avec l’intégration au shell, vous pouvez modifier cette commande à l’invite de commande. Exécutez openai explore --help pour consulter la liste des shells pris en charge et des raccourcis clavier.

Authentification

La CLI lit votre clé API dans la variable 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 des API d’administration, définissez plutôt OPENAI_ADMIN_KEY. Le SDK choisit la clé d’administration ou la clé API par défaut selon le point de terminaison appelé.

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

Cas d’utilisation

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

• Générez des fichiers locaux, par exemple des images ou des enregistrements de synthèse vocale.
• Extrayez des données structurées au format JSONL pour les traiter ensuite dans le shell.
• Utilisez l’API Responses dans le cloud pour traiter des fichiers, utiliser l’ordinateur et accéder à des informations à jour sur le Web.
• Créez des projets et des clés API avec les API d’administration.

Utilisez la CLI directement dans le terminal pour les requêtes ponctuelles, ou appelez-la depuis des scripts lorsque des agents doivent répéter un traitement par lots sur des fichiers et des artefacts générés.

CLI ou sous-agents dans Codex

Utilisez la CLI pour les opérations d’API que vous souhaitez inspecter et réexécuter, par exemple pour extraire des données par lots, transformer des fichiers, générer des artefacts ou choisir explicitement un modèle. Faites appel aux sous-agents pour les tâches qui demandent du discernement, comme explorer du code, comparer des hypothèses, déboguer ou examiner des modifications.

Options globales

Ces options s’appliquent à toutes les commandes :

Ce guide présente les usages de la CLI. Pour connaître les arguments et la structure des réponses à jour pour chaque famille d’API, consultez la référence de l’API.

Vous pouvez aussi modifier l’URL de base pour que la CLI utilise un autre point de terminaison compatible, par exemple un déploiement qui prend en charge d’autres modèles ou seulement une partie des fonctionnalités de l’API.

Responses

Utilisez l’API Responses pour générer du texte, extraire des données structurées, effectuer une recherche web, analyser le contenu de fichiers et exécuter de façon répétée des scripts de traitement par lots é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 complet de l’API. Les exemples de cette page n’en montrent que quelques champs représentatifs, comme id, status, model, output et usage.

Dans la sortie de l’API Responses, des éléments d’un autre type, par exemple des éléments de raisonnement, peuvent précéder le message de l’assistant. Pour obtenir le texte de l’assistant, sélectionnez le message selon son type, sans supposer qu’il se trouve toujours dans output[0] :

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

Ajoutez un fichier local au prompt

Pour intégrer un fichier local, construisez le prompt directement dans la ligne de commande à l’aide d’une 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.

Transmission du corps d’une requête

Utilisez des options pour les valeurs scalaires courtes. Pour les prompts multilignes, les outils, les fichiers ou les corps de requête imbriqués, utilisez un here-document au format YAML. Vous pouvez y inclure les mêmes champs que ceux que vous passeriez en options.

Prêtez attention aux chaînes qui ressemblent à du YAML, en particulier aux prompts qui contiennent : ou {}. Lorsque vous passez ces valeurs en options, l’analyseur généré peut les interpréter comme du YAML structuré plutôt que comme du texte brut. Si un prompt ressemble à un extrait de configuration, placez-le sous input: | dans un corps de requête 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.

Si vous devez assembler le prompt dans le shell, construisez un corps de requête YAML et transmettez-le à la commande via 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 attendent des données JSON de structure stable. Enregistrez les schémas réutilisables sur disque :

Enregistrez ce schéma 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 même entrée peut produire plusieurs enregistrements, demandez au modèle de renvoyer un tableau, puis convertissez-le en JSONL pour que les commandes suivantes du shell puissent traiter un enregistrement par ligne :

Enregistrez ce schéma 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 structurée et les commandes suivantes du shell reçoivent un objet JSON par ligne.

Recherche web

L’API 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 utiliser un fichier téléversé, par exemple un PDF, créez d’abord le fichier dans l’API, récupérez son identifiant et passez-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.

Dans les versions récentes de la CLI générée, chaque fichier local passé en option est envoyé dans une partie distincte d’une requête multipart, avec son nom et son type de contenu. Si le téléversement d’un fichier local échoue avec une erreur de type UploadFile, mettez la CLI à jour et réessayez.

Images

Générez une image

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

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

Les commandes d’image ne prennent pas encore en charge l’option --output nativement. Pour la génération d’images, vous devez donc extraire b64_json et en décoder vous-même le contenu.

Avec gpt-image-2, omettez --input-fidelity, car 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 pour les arrière-plans transparents. Le modèle accepte aussi davantage de valeurs pour --size que les modèles GPT Image précédents, à condition que la résolution demandée respecte les contraintes de taille de l’API Images.

Modifiez une image

Une fois la requête de modification terminée avec succès, extrayez les données en base64 de la même manière :

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 la CLI à jour et réessayez.

Synthèse vocale

Créez un fichier MP3 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 un lecteur audio installé sur votre machine. Sur macOS, utilisez la commande suivante :

afplay speech.mp3

Utilisez --instructions pour préciser la manière de prononcer le texte et --input pour fournir le texte à prononcer. Les instructions peuvent préciser le rythme, l’énergie, la chaleur de la voix, le registre, les mots à accentuer ou le 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 l’utiliser dans un pipeline shell :

Commande :

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

Sortie :

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

L’exemple ci-dessus utilise le modèle recommandé pour la transcription de fichiers. Les exemples spécialisés ci-dessous restent utilisables dans les intégrations existantes :

Pour obtenir l’horodatage de chaque mot, demandez une transcription au format 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 associer chaque segment à son locuteur, 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 inclut le champ segments[].speaker. Si vous utilisez le même modèle de diarisation et demandez le format json standard, la réponse contient le texte de la transcription sans indiquer les locuteurs.

API d’administration

Utilisez les API d’administration pour gérer votre organisation, créer des identifiants d’accès, assurer la conformité et suivre l’utilisation. Définissez OPENAI_ADMIN_KEY, puis appelez les commandes générées admin:organization:*.

Pour créer de nouveaux identifiants d’accès pour une 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

Lorsque vous créez un compte de service dans ce projet, l’API renvoie la clé API complète du 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-..."
  }
}

Ce script enregistre la réponse de création du projet dans project.json, en extrait l’identifiant du projet pour le passer à la commande suivante, puis enregistre la réponse de création du compte de service dans service-account.json. Il écrit ensuite la clé renvoyée 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 à jour de l’API d’administration. Vérifiez à qui vous accordez l’accès aux clés d’administration.