OpenAI CLI

Installatie

Installeren met Homebrew

brew install openai/tools/openai

Installeren met Go

Om de CLI lokaal te testen of te installeren, is Go versie 1.26 of later vereist.

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

Na het uitvoeren van go install wordt het binary-bestand geplaatst in je Go bin-directory:

  • Standaardlocatie: $HOME/go/bin (of $GOPATH/bin als GOPATH is ingesteld).
  • Pad controleren: Voer go env GOPATH uit om de basisdirectory te zien.

Als commando's na installatie niet worden gevonden, voeg dan de Go bin-directory toe aan je PATH:

# Voeg toe aan je shell-profiel (.zshrc, .bashrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"

Opmerking: De eerste geschikte interactieve openai-run slaat stilzwijgend Tab-sneltoetsen op voor de image picker voor toekomstige Bash-, zsh- en fish-sessies. Open een nieuwe terminal om deze te gebruiken. PowerShell behoudt normale Tab-aanvulling; druk op Enter na openai images generate om de picker te openen.

Update-meldingen

Wanneer stdin, stdout en stderr terminals zijn, controleert openai op nieuwere stabiele releases. Er wordt een melding in platte tekst toegevoegd onder de helptekst, maximaal eens per zeven dagen.

De controle wordt volledig overgeslagen bij:

  • Expliciete help-aanvragen;
  • Commando's;
  • Aanvullingen (completion);
  • CI-omgevingen;
  • Omgeleide streams (redirected streams).

De melding bevat een update-commando wanneer de CLI de installatiemethode kan verifiëren:

  • Geverifieerde Homebrew-installaties gebruiken: brew upgrade --cask openai/tools/openai.
  • Go-commando's vereisen een geverifieerd binary-bestand, een beschikbaar Go-commando en een expliciete matching GOBIN.
  • Bij aangepaste GOOS- of GOARCH-instellingen wordt verwezen naar de installatiehandleiding.
  • Upgrades naar hoofdversie 2 of later verwijzen ook naar de installatiehandleiding.
  • Onbekende installaties ontvangen een link naar de installatiehandleiding.

De CLI installeert updates nooit automatisch. Controles maken gebruik van openbare GitHub release-metadata zonder API-gegevens, maximaal eens per dag. De controles houden rekening met HTTPSPROXY en NOPROXY (inclusief kleine letters). De detectie van updates wacht maximaal 200 milliseconden; mislukte controles blijven stil.

Gebruik OPENAICLINOUPDATECHECK=1 om controles en meldingen uit te schakelen.

Lokaal Uitvoeren

Na het klonen van de git-repository voor dit project kun je het scripts/run-script gebruiken om de tool lokaal uit te voeren:

./scripts/run args...

Gebruik

De CLI volgt een op resources gebaseerde commandostructuur: openai <resource> [subresource...] <command> [flags...]

Authenticatie

Standaard API-endpoints vereisen een API-sleutel:

export OPENAI_API_KEY="sk-..."
openai responses create \
--input "Say this is a test" \
--model gpt-5.5

Admin-endpoints vereisen een admin API-sleutel:

export OPENAI_ADMIN_KEY="sk-admin-..."
openai admin organization usage completions \
--start-time 1735689600 \
--end-time 1735776000 \
--bucket-width 1d

Help en Navigatie

Blader door elke groep met --help, bijvoorbeeld openai admin --help of openai admin organization --help. Bestaande colon-commando's zoals openai admin:organization:usage completions blijven werken.

Voer openai uit om commandogroepen per taak te bekijken, inclusief beschrijvingen. Groepshulp scheidt acties van geneste commandogroepen en somt elk direct commando op.

Help werkt zonder API-sleutel of netwerkverbinding:

  • openai help setup — Voer je API-sleutel veilig in.
  • openai images generate --help — Voorbeelden en elke optie voor afbeeldingen.
  • openai help images generate — Dezelfde volledige help voor afbeeldingen.
  • openai --help — Commandogroepen en globale opties.

Voeg --help (of -h) toe aan elk commando voor de volledige helppagina. openai help COMMAND toont dezelfde pagina. Commandopagina's tonen globale opties; gebruik openai --help voor volledige beschrijvingen.

Geavanceerde Functies

  • Tab-aanvulling: Volgt dezelfde groepsvolgorde en ondersteunt helponderwerpen en bestandspaden. Na een upgrade moet de shell-aanvulling worden herladen om het nieuwe gedrag voor bestandspaden te activeren.
  • Commando-insertie: Maak gebruik van voorbeelden, setup-begeleiding en herstelcommando's. Ctrl+X, gevolgd door Tab, doorzoekt suggesties zonder ze uit te voeren. Double Tab is een optionele binding voor Bash, zsh en fish.
  • Output-formaten: Succesvolle JSON-responses printen standaard leesbare tekst, ook in pipes. Gebruik --format json of --format jsonl in scripts die API-data parsen.

Werken met Bestanden

Upload een lokaal bestand met een expliciet doel, inspecteer de metadata en download vervolgens de inhoud:

openai files upload "upload space.txt" --purpose user_data
openai files get file-example
openai files download file-example --output "downloaded copy.txt"
openai files download file-example > copy.txt

(Vervang file-example door het geretourneerde bestand-ID. Upload gebruikt een gewoon pad, zonder toegevoegde @).

Afbeeldingen Genereren

openai images generate --prompt "A tiny orange robot" slaat afbeeldingen op in ~/Downloads/gpt-images/ en print de paden.

  • De CLI gebruikt gpt-image-2.5-sunburst bij het opslaan zonder expliciet model.
  • Gebruik --model voor een specifiek ID, --name voor een bestandsnaam, of --output-dir voor een bestaande directory.
  • --format json retourneert API-data zonder de afbeelding op te slaan.
  • images edit slaat nieuwe resultaten op terwijl bronbestanden behouden blijven.
  • images create-variation is stopgezet. Gebruik images edit met een GPT Image-model en een prompt.
  • openai images preview "path/to/image.png" toont een opgeslagen afbeelding opnieuw zonder API-verzoek.

Foutafhandeling

Fouten printen standaard actiegerichte samenvattingen naar stderr.

  • Gebruik --format-error json voor originele API-foutdetails.
  • --transform-error extraheert foutgegevens onafhankelijk van de succesvolle output.
  • Malformed of lege fout-bodies ontvangen een veilige diagnose; de HTTP-status wordt alleen opgenomen wanneer de SDK deze behoudt.

Omgevingsvariabelen

OmgevingsvariabeleVerplichtStandaardwaarde
OPENAIAPIKEYneenull
OPENAIADMINKEYneenull
OPENAIORGIDneenull
OPENAIPROJECTIDneenull
OPENAIWEBHOOKSECRETneenull
OPENAICUSTOMHEADERSneenull
OPENAIMTLSCLIENTCERTFILEneenull
OPENAIMTLSCLIENTKEYFILEneenull
OPENAIUNTRUSTEDSTDINneefalse

Globale Vlaggen

  • --api-key (of OPENAIAPIKEY env var)
  • --admin-api-key (of OPENAIADMINKEY env var)
  • --organization (of OPENAIORGID env var)
  • --project (of OPENAIPROJECTID env var)
  • --webhook-secret (of OPENAIWEBHOOKSECRET env var)
  • --mtls-client-cert-file (of OPENAIMTLSCLIENTCERTFILE env var)
  • --mtls-client-key-file (of OPENAIMTLSCLIENTKEYFILE env var)
  • --help - Toon command-line gebruik.
  • --debug - Schakel debug-logging in (inclusief HTTP request/response details). Deel deze logs niet als ze gevoelige gegevens bevatten.
  • --version, -v - Toon de CLI-versie.
  • --base-url - Gebruik een aangepaste API backend URL (HTTPS vereist, behalve voor localhost/loopback IP's).
  • --header, -H - Voeg een letterlijke request-header toe als Naam: Waarde.
  • --format - Wijzig het output-formaat (auto, text, explore, json, jsonl, pretty, raw, yaml).
  • --format-error - Wijzig het stderr fout-formaat (auto, text, explore, json, jsonl, pretty, raw, yaml).
  • --transform - Transformeer de data-output via GJSON-syntaxis.
  • --transform-error - Transformeer de fout-output via GJSON-syntaxis.

Request-headers

Gebruik --header of -H voor of na een resource-commando:

openai --header 'X-Trace-ID: example-123' models list \
-H 'X-Client-Label: local,manual'

Waarden zijn letterlijk; spaties en tabs worden verwijderd. Als een naam wordt herhaald, wint de laatste waarde.

Voor beveiligde headers is het aanbevolen om OPENAICUSTOMHEADERS direct in de omgeving van de CLI in te stellen. Dit voorkomt dat geheimen in de shell-geschiedenis terechtkomen. De variabele accepteert één Naam: Waarde vermelding per regel:

export OPENAI_CUSTOM_HEADERS='X-Trace-ID: example-123
X-Client-Label: local,manual'
openai models list

Mutual TLS (mTLS)

Mutual TLS bevindt zich momenteel in bèta. Om dit te activeren, volg de instructies van het OpenAI Mutual TLS Beta Program.

Om API-key verzoeken te authenticeren met een mTLS-clientcertificaat, lever je het clientcertificaat en de private key als aparte PEM-bestanden:

export OPENAI_MTLS_CLIENT_CERT_FILE=/run/secrets/openai/client-chain.pem
export OPENAI_MTLS_CLIENT_KEY_FILE=/run/secrets/openai/client.key
export OPENAI_BASE_URL=https://mtls.api.openai.com/v1
openai files list

Beide mTLS-bestanden moeten samen worden geconfigureerd. Bewaar de private key in een bestand met beperkte rechten. De CLI selecteert niet automatisch een mTLS-endpoint; configureer OPENAIBASEURL of --base-url expliciet.

Bestanden als Argumenten Doorgeven

Voor JSON-inputwaarden leest @myfile.ext de inhoud van lokale bestanden:

openai <command> --arg @abe.jpg

Bestanden kunnen ook worden doorgegeven binnen JSON- of YAML-blobs:

openai <command> --arg '{image: "@abe.jpg"}'
# Of via YAML:
openai <command> <<YAML
arg:
  image: "@abe.jpg"
YAML

Bij het pipen van JSON of YAML van een onbetrouwbare bron, schakel dan de untrusted-stdin modus in:

untrusted-producer | OPENAI_UNTRUSTED_STDIN=1 openai <command> --file ./upload.txt

In deze modus worden waarden via stdin behandeld als letterlijke data; @, @file:// en @data:// referenties lezen geen lokale bestanden.

Om een string-literal door te geven die begint met een @-teken, kun je het teken escapen:

openai <command> --username '\@abe'

Expliciete Codering

De CLI gebruikt filetype sniffing om te bepalen of inhoud als string-literal (platte tekst) of base64-encoded string (binary) moet worden verzonden. Voor expliciete codering gebruik je:

  • @file://myfile.txt (voor string-codering)
  • @data://myfile.dat (voor base64-codering)

Let op: Absolute paden beginnen met @file:/// of @data:///.

Koppelen van Go SDK-versies

Voor ontwikkeldoeleinden kun je de CLI koppelen aan een andere versie van de OpenAI Go SDK met het ./scripts/link script.

Koppelen aan een specifieke versie uit een repository (branch, tag of commit hash):

./scripts/link github.com/org/repo@version

Koppelen aan een lokale kopie van de SDK:

./scripts/link ../path/to/openai-go

Bijdragen

Deel bugrapporten en feature-verzoeken via GitHub issues. Pull requests zijn beperkt tot repository-collaborators; pull requests van niet-collaborators worden niet geaccepteerd. Zie CONTRIBUTING.md voor het beleid en de ontwikkelhandleiding. Voor beveiligingskwetsbaarheden, volg SECURITY.md.

Licentie

Copyright 2026 OpenAI. Dit project is gelicenseerd onder de Apache License 2.0.