Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

OpenAI CLI

Nutze die OpenAI API direkt im Terminal.

Mit dem Befehlszeilenwerkzeug openai kannst du die OpenAI API direkt im Terminal aufrufen.

Installation

Installiere die CLI mit Homebrew:

brew install openai/tools/openai

Alternativ kannst du sie mit Go ab Version 1.25 installieren:

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

Ältere Versionen des Python-SDK installierten auch einen früheren openai-Befehl. Wenn du das Paket schon installiert hattest und der Befehl bei dir von dieser Anleitung abweicht, ruft deine Shell möglicherweise noch das ältere Programm auf. Neuinstallationen der CLI sind davon nicht betroffen.

Befehle finden

Führe openai explore im Terminal aus, um die verfügbaren Befehle zu durchsuchen. Das geht schon, bevor du einen API-Schlüssel einrichtest. Gib eine Aufgabe wie count tokens offline ein, um den Befehl openai tokenizer count zu finden. Markiere mit den Pfeiltasten einen Treffer. Drücke Enter, um ihn auszuwählen, oder Escape, um abzubrechen.

Explore zeigt den ausgewählten Befehl an, ohne ihn auszuführen. Mit der Shell-Integration kannst du den Befehl an der Eingabeaufforderung bearbeiten. Mit openai explore --help siehst du, welche Shells und Tastenkürzel unterstützt werden.

Authentifizierung

Die CLI liest deinen API-Schlüssel aus OPENAI_API_KEY:

Befehl:

export OPENAI_API_KEY="sk-..."

Wenn du noch keinen API-Schlüssel hast, erstelle einen im Dashboard.

Für Endpunkte der Admin API setzt du stattdessen OPENAI_ADMIN_KEY. Je nach aufgerufenem Endpunkt wählt das SDK den Admin-Schlüssel oder den standardmäßigen API-Schlüssel aus.

Um einen anderen API-Host zu verwenden, setze OPENAI_BASE_URL.

Anwendungsfälle

Nutze die CLI für Aufgaben, die sich gut im Terminal erledigen lassen:

  • Erzeuge lokale Dateien, etwa Bilder oder Audiodateien mit gesprochenem Text.
  • Extrahiere strukturierte Daten im JSONL-Format, um sie in der Shell weiterzuverarbeiten.
  • Nutze Responses in der Cloud für die Arbeit mit Dateien, für die Computernutzung und für Anfragen mit aktuellen Informationen aus dem Web.
  • Erstelle Projekte und API-Schlüssel mit den Admin APIs.

Für einzelne Anfragen kannst du die CLI direkt im Terminal aufrufen. Nutze sie in Skripten, wenn Agenten Dateien und erzeugte Artefakte wiederholt im Stapel verarbeiten sollen.

CLI und Subagenten in Codex

Nutze die CLI für API-Aufgaben, deren Ablauf du prüfen und erneut ausführen möchtest. Dazu gehören die Datenextraktion im Stapel, das Umwandeln von Dateien, das Erzeugen von Artefakten oder die gezielte Modellauswahl. Setze Subagenten ein, wenn die Aufgabe Urteilsvermögen erfordert, etwa beim Erkunden von Code, beim Vergleichen von Hypothesen, bei der Fehlersuche oder beim Prüfen von Änderungen.

Globale Optionen

Diese Optionen kannst du bei verschiedenen Befehlen verwenden:

Option Funktion
--format Gibt Antworten als auto, json, jsonl, pretty, raw, yaml oder explore aus.
--transform Extrahiert Antwortdaten vor der Ausgabe anhand eines GJSON-Pfads oder strukturiert sie um.
--debug Gibt Details zu Anfrage und Antwort auf stderr aus. Die Autorisierungsdaten werden unkenntlich gemacht. Prüfe die Header, bevor du Protokolle teilst.

Diese Anleitung zeigt typische Abläufe mit der CLI. Die aktuellen Argumente und Antwortstrukturen für jede API-Familie findest du in der API-Referenz.

Über die Basis-URL kannst du die CLI auch auf einen anderen kompatiblen Endpunkt ausrichten, etwa auf eine Bereitstellung, die andere Modelle oder nur einen Teil der API-Funktionen unterstützt.

Responses

Mit Responses kannst du Texte generieren, strukturierte Daten extrahieren, das Web durchsuchen und Dateiinhalte auswerten. Du kannst Responses auch in wiederholt ausführbaren Batch-Skripten nutzen, die Codex geschrieben hat.

Erste Anfrage senden

Befehl:

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

Ausgabe:

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

Standardmäßig gibt die CLI das vollständige Antwortobjekt der API aus. Die Beispiele auf dieser Seite zeigen ausgewählte Felder wie id, status, model, output und usage. Die übrigen Felder sind ausgelassen.

In der Ausgabe von Responses können vor der Nachricht des Assistenten andere Elemente stehen, etwa Reasoning-Elemente. Wenn du den Antworttext des Assistenten brauchst, wähle das Nachrichtenelement anhand seines Typs aus. Es steht nicht immer an der Position output[0]:

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

Eine lokale Datei in den Prompt einfügen

Um den Inhalt einer lokalen Datei einzufügen, setze den Prompt direkt im Befehl per Befehlssubstitution zusammen:

openai 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'

Ausgabe:

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

Anfragedaten übergeben

Für kurze skalare Werte genügen Befehlszeilenoptionen. Für mehrzeilige Prompts, Tools, Dateien oder verschachtelte Anfragedaten verwende ein Here-Dokument im YAML-Format. Darin kannst du dieselben Anfragefelder angeben, die du sonst als Optionen übergeben würdest.

Achte auf Zeichenfolgen, die wie YAML aussehen, besonders bei Prompts mit : oder {}. Wenn du solche Werte als Optionen übergibst, interpretiert der generierte Parser sie möglicherweise als strukturiertes YAML statt als reinen Text. Wenn ein Prompt wie eine Konfiguration aussieht, schreibe ihn im YAML-Anfragetext unter input: |:

Befehl:

openai 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

Ausgabe:

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

Wenn du den Prompt in der Shell zusammensetzen musst, erstelle den YAML-Anfragetext und leite ihn über eine Pipe an den Befehl weiter:

{
  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'

Strukturierte Daten als JSON speichern

Nutze strukturierte Ausgaben, wenn nachgelagerte Skripte JSON mit einer festen Struktur benötigen. Speichere wiederverwendbare Schemas als Dateien.

Speichere dieses Schema als schema.json:

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

Befehl:

openai 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'

Ausgabe:

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

Strukturierte Datensätze als JSONL ausgeben

Wenn aus einer Eingabe mehrere Datensätze entstehen können, fordere vom Modell ein Array an. Wandle es in JSONL um, damit die nächsten Shell-Befehle einen Datensatz pro Zeile verarbeiten können:

Speichere dieses Schema als records-schema.json:

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

Befehl:

: > 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

Die Modellantwort bleibt dabei strukturiert. Für die weitere Verarbeitung in der Shell erhältst du ein JSON-Objekt pro Zeile.

Websuche

Mit Responses kannst du gehostete Tools über denselben YAML-Anfragetext aufrufen:

Befehl:

openai 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

Ausgabe:

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

Dateien als Eingabe

Wenn du eine Datei wie ein PDF verwenden möchtest, lade sie zuerst hoch, speichere ihre ID und übergib diese als input_file.file_id:

Befehl:

FILE_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

Ausgabe:

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

Neuere generierte CLI-Versionen senden lokale Dateien, die du per Option angibst, als Teile einer Multipart-Anfrage. Sie übermitteln dabei Dateinamen und Inhaltstyp als Metadaten. Wenn das Hochladen einer lokalen Datei mit einem Typfehler für UploadFile fehlschlägt, aktualisiere die CLI und versuche es erneut.

Bilder

Ein Bild generieren

Generiere ein Bild, extrahiere die Base64-kodierten Daten und dekodiere sie, um eine Bilddatei zu erhalten:

Befehl:

openai 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'

Ausgabe:

wrote hero.png

Die Bildbefehle unterstützen --output derzeit noch nicht direkt. Bei der Bildgenerierung musst du daher b64_json selbst extrahieren und dekodieren.

Lass bei gpt-image-2 die Option --input-fidelity weg. Das Modell verarbeitet Bildeingaben immer mit hoher Detailtreue. Transparente Hintergründe sind als Vorschaufunktion verfügbar. Verwende --background transparent mit png (Standard) oder webp. Für jpeg werden transparente Hintergründe nicht unterstützt. Das Modell unterstützt für --size mehr Werte als frühere GPT Image-Modelle, sofern die gewünschte Auflösung die Größenvorgaben der Image API erfüllt.

Ein Bild bearbeiten

Nach einer erfolgreichen Bearbeitungsanfrage extrahierst du die Base64-kodierten Bilddaten genauso wie bei der Bildgenerierung:

Befehl:

openai 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'

Ausgabe:

wrote hero-edited.png

Wenn du ein lokales Bild zur Bearbeitung hochlädst und dabei ein Typfehler für UploadFile auftritt, aktualisiere die CLI und versuche es erneut.

Sprachausgabe

Diese Beispiele für die Speech API verwenden das veraltete Modell gpt-4o-mini-tts. Es wird am 6. Januar 2027 abgeschaltet. Steige auf gpt-realtime-2.1-mini um und nutze dafür die Realtime API. Für den Umstieg reicht es nicht aus, in openai audio:speech create nur die Modell-ID auszutauschen. Weitere Informationen findest du im Hinweis zur Einstellung der Modelle.

Erstelle mit der Speech API eine lokale MP3-Datei:

Befehl:

openai 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

Ausgabe:

Wrote output to: speech.mp3

Spiele die Datei mit einem Audioprogramm auf deinem Rechner ab. Unter macOS geht das so:

afplay speech.mp3

Mit --instructions legst du die Sprechweise fest. Mit --input gibst du den Text an, der gesprochen werden soll. In den Anweisungen kannst du zum Beispiel das Tempo, die Energie, die Wärme der Stimme, den Grad der Förmlichkeit, die Betonung oder die Zielgruppe angeben:

openai 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

Transkription

Gib das Transkript für die Weiterverarbeitung in Shell-Pipelines als reinen Text aus:

Befehl:

openai audio:transcriptions create \
  --model gpt-transcribe \
  --file ./speech.mp3 \
  --transform text \
  --raw-output

Ausgabe:

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

Das Beispiel verwendet das empfohlene Modell für die Transkription von Dateien. Die folgenden Beispiele für spezielle Anwendungsfälle stehen für bestehende Integrationen weiterhin zur Verfügung:

whisper-1 und gpt-4o-transcribe-diarize sind veraltet und werden am 26. Februar 2027 abgeschaltet. Beim Wechsel zum empfohlenen Transkriptionsmodell stehen dir nicht mehr alle bisherigen Ausgabeformate und Metadatenfelder zur Verfügung. Weitere Informationen findest du im Hinweis zur Einstellung der Modelle und in der Anleitung zu Transkriptionsworkflows.

Gewünschte Ausgabe Befehlsoptionen
Untertiteldateien --model whisper-1 --response-format srt oder --response-format vtt
Zeitstempel für Segmente oder Wörter --model whisper-1 --response-format verbose_json
Transkript mit Kennzeichnung der sprechenden Personen --model gpt-4o-transcribe-diarize --response-format diarized_json

Für Zeitstempel auf Wortebene fordere das ausführliche Transkriptionsformat an:

Befehl:

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

Ausgabe:

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

Wenn die Ausgabe kennzeichnen soll, wer spricht, verwende das Modell für die Sprechertrennung und fordere diarized_json an:

Befehl:

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

Ausgabe:

{
  "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 unterstützt json, text, srt, verbose_json und vtt. Das Format diarized_json enthält das Feld segments[].speaker. Verwendest du mit demselben Modell für die Sprechertrennung das einfache Format json, enthält die Antwort den Transkripttext ohne Kennzeichnung der sprechenden Personen.

Admin APIs

Mit den Admin APIs kannst du Organisationen verwalten, Zugangsdaten bereitstellen, Compliance-Aufgaben erledigen und die Nutzung überwachen. Setze OPENAI_ADMIN_KEY und rufe dann die generierten admin:organization:*-Befehle auf.

Um neue Zugangsdaten für den maschinellen Zugriff bereitzustellen, erstelle ein Projekt, lege darin ein Dienstkonto an und verwende den zurückgegebenen API-Schlüssel.

Projekt, Dienstkonto und API-Schlüssel erstellen

Wenn du in diesem Projekt ein Dienstkonto erstellst, erhältst du den vollständigen API-Schlüssel für das Konto.

Befehl:

# 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

Ausgabe:

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

Das Skript speichert die Antwort für das Projekt in project.json, liest daraus die Projekt-ID und übergibt sie an den nächsten Befehl. Es speichert die Antwort für das Dienstkonto in service-account.json und schreibt den zurückgegebenen Schlüssel in .env als OPENAI_API_KEY=.... Behandle beide JSON-Dateien als vertraulich. Nimm project.json, service-account.json und .env in .gitignore auf, bevor du dieses Verfahren in einem Repository verwendest.

Weitere Funktionen findest du im Leitfaden zu den Admin APIs und in der aktuellen Referenz zur Administration API. Prüfe sorgfältig, wem du Zugriff auf Admin-Schlüssel gewährst.