openai/openai-cli: Official CLI for the OpenAI API · GitHub

The official CLI for the OpenAI REST API.

brew set up openai/instruments/openai

To take a look at or set up the CLI regionally, you want Go model 1.26 or later put in.

go set up 'github.com/openai/openai-cli/cmd/openai@newest'

Once you might have run go set up, the binary is positioned in your Go bin listing:

• Default location: $HOME/go/bin (or $GOPATH/bin if GOPATH is about)
• Check your path: Run go env GOPATH to see the bottom listing

If instructions aren’t discovered after set up, add the Go bin listing to your PATH:

# Add to your shell profile (.zshrc, .bashrc, and so on.)
export PATH="$PATH:$(go env GOPATH)/bin"

The first eligible interactive openai run quietly saves picture picker Tab
shortcuts for future Bash, zsh, and fish periods. Open a brand new terminal to make use of
them. See shortcut setup and removal for
necessities and opt-out. PowerShell retains regular Tab completion; press Enter
after openai pictures generate to open the picker.

Bare openai checks for newer steady releases when stdin, stdout, and stderr are terminals.
It provides a plain-text discover beneath assist, at most as soon as each seven days.
Explicit assist, instructions, completion, CI, and redirected streams skip the examine solely.

The discover contains an replace command when the CLI can confirm its set up methodology.
Verified Homebrew installations use brew improve --cask openai/instruments/openai.
Go instructions require a verified binary, an out there Go command, and an express matching GOBIN.
Custom GOOS or GOARCH settings choose the set up information as a substitute.
Go upgrades to main model 2 or later additionally choose the set up information.
Unknown installations obtain the installation-guide hyperlink as a substitute.
The CLI by no means installs updates robotically.

Checks use public GitHub launch metadata with out API credentials, at most as soon as every day.
Checks respect HTTPS_PROXY and NO_PROXY, together with their lowercase types.
Update discovery waits at most 200 milliseconds. Failed checks stay silent.
Package-manager availability can lag a brand new GitHub launch.
Set OPENAI_CLI_NO_UPDATE_CHECK=1 to disable checks and notices.

After cloning the git repository for this challenge, you should use the
scripts/run script to run the software regionally:

The CLI follows a resource-based command construction:

openai <useful resource> [subresource...] <command> [flags...]

Standard API endpoints require an API key:

export OPENAI_API_KEY="sk-..."

openai responses create 
  --input "Say it is a take a look at" 
  --model gpt-5.5

Admin endpoints require an admin API key:

export OPENAI_ADMIN_KEY="sk-admin-..."

openai admin group utilization completions 
  --start-time 1735689600 
  --end-time 1735776000 
  --bucket-width 1d

Browse every group with --help, for instance openai admin --help or
openai admin group --help. Existing colon instructions equivalent to
openai admin:group:utilization completions proceed to work.

Run openai to browse command teams by process, with descriptions for every group.
Group assist separates actions from nested command teams and lists each instant command.
Help works with out an API key or community connection:

openai assist setup                  # Enter your API key safely
openai pictures generate --help      # Example and each picture possibility
openai assist pictures generate        # The similar full picture assist
openai --help                      # Command teams and international choices

Add --help (or -h) to any command for its full assist web page.
openai assist COMMAND exhibits the identical web page.
Command pages listing international choices. Use openai --help for his or her full descriptions.
You can place --help after legitimate command choices.
The previous assist --all spelling prints migration steering and the whole web page.
Command conduct, defaults, and output codecs stay unchanged.
Tab completion follows the identical group order and helps assist subjects and file enter paths.
After upgrading, reload shell completion to allow the brand new file-path conduct.
Older loaded completion scripts hold their earlier conduct till refreshed.

Enable command insertion to fill your command line
from examples, setup steering, and restoration instructions. Ctrl+X, then Tab searches solutions
with out working them. Double Tab is an non-obligatory binding for Bash, zsh, and fish.

Successful JSON responses print readable textual content by default, together with in pipes.
Use --format json or --format jsonl in scripts that parse API information.
See reading command results for extraction, binary
output, and the scope of readable presentation.

Upload an area file with an express objective, examine its metadata, then obtain its contents:

openai information add "add area.txt" --purpose user_data
openai information get file-example
openai information obtain file-example --output "downloaded copy.txt"
openai information obtain file-example > copy.txt

Replace file-example with the returned file ID. Upload takes a plain path, with out an added @.
create, retrieve, content material, and their present flags stay out there.
See working with files for literal filenames, output codecs, and script examples.

openai pictures generate --prompt "A tiny orange robotic" saves pictures to
~/Downloads/gpt-images/ and prints their paths, together with in pipes. The CLI
makes use of gpt-image-2.5-sunburst when saving with out an express mannequin or legacy
response format. Use --model for one more precise ID, --name for a filename,
or --output-dir for an present listing. Existing information are saved.
--format json returns API information with out saving or making use of the CLI preset.
pictures edit additionally saves new outcomes whereas retaining supply information.
pictures create-variation is retired and not out there. To create a
variation, use pictures edit with a GPT Image mannequin and a immediate. See
image generation and saving for instructions
and defaults.

openai pictures preview "path/to/picture.png" redisplays a saved picture with out an
API request. Use openai pictures inline on or off to recollect whether or not future
saved pictures seem robotically. Per-command --inline auto, on or off
overrides that setting. on additionally permits a picture font in native Apple Terminal.

Errors print actionable summaries to stderr by default. Use --format-error json
for authentic API error particulars, together with unknown fields and SDK-reported stream
error occasions. For these occasions, extraction paths embrace the error envelope,
for instance --transform-error error.code. Explicit --format
values json, jsonl, uncooked, and yaml additionally apply to errors until overridden
by --format-error; an express --format-error auto or textual content restores summaries.
--transform-error extracts error information independently of profitable output.
Malformed or empty error our bodies obtain a protected diagnostic; HTTP standing is included
solely when the SDK retains it. Summaries omit rejected values and request URLs;
express API error particulars can comprise server-supplied delicate information.

• --api-key (may also be set with OPENAI_API_KEY env var)
• --admin-api-key (may also be set with OPENAI_ADMIN_KEY env var)
• --organization (may also be set with OPENAI_ORG_ID env var)
• --project (may also be set with OPENAI_PROJECT_ID env var)
• --webhook-secret (may also be set with OPENAI_WEBHOOK_SECRET env var)
• --mtls-client-cert-file (may also be set with OPENAI_MTLS_CLIENT_CERT_FILE env var)
• --mtls-client-key-file (may also be set with OPENAI_MTLS_CLIENT_KEY_FILE env var)
• --help – Show command line utilization
• --debug – Enable debug logging. This contains HTTP request/response particulars and our bodies; don’t share debug logs if they might comprise delicate payloads.
• --version, -v – Show the CLI model
• --base-url – Use a customized API backend URL. HTTPS is required apart from
  localhost or literal loopback IP addresses equivalent to 127.0.0.1 and ::1.
  This additionally applies to OPENAI_BASE_URL; distant HTTP backends should allow HTTPS.
• --header, -H – Add a literal request header as Name: Value; repeat for a number of headers
• --format – Change the output format (auto, textual content, discover, json, jsonl, fairly, uncooked, yaml); auto selects readable textual content until extracting information
• --format-error – Change the stderr error format (auto, textual content, discover, json, jsonl, fairly, uncooked, yaml); auto selects readable summaries until extracting error information
• --transform – Transform the information output utilizing GJSON syntax
• --transform-error – Transform the error output utilizing GJSON syntax

Use --header or -H earlier than or after a useful resource command:

openai --header 'X-Trace-ID: example-123' fashions listing 
  -H 'X-Client-Label: native,handbook'

Values are literal: commas and colons are preserved, and @ prefixes don’t
learn information. Surrounding areas and tabs are trimmed from values. -H 'X-Example:'
sends an empty worth. If a reputation is repeated, the final worth wins no matter
case, overriding default and endpoint-specific headers. Headers managed by the
HTTP transport, equivalent to Host and Content-Length, retain the transport’s
conduct. Supplied header values are hidden in assist and redacted in debug logs.

For credential-bearing headers, have a secret supervisor or trusted launcher set
OPENAI_CUSTOM_HEADERS instantly within the CLI’s atmosphere. This retains credentials
out of command arguments and avoids typing literal secrets and techniques into shell historical past.
The variable accepts one Name: Value entry per line. For instance, with
non-sensitive values:

export OPENAI_CUSTOM_HEADERS='X-Trace-ID: example-123
X-Client-Label: native,handbook'
openai fashions listing

--header and endpoint-specific header flags override matching atmosphere
entries. Environment header values are additionally redacted in debug logs. Use
OPENAI_API_KEY and OPENAI_ADMIN_KEY for traditional API and admin authentication.

Mutual TLS is at the moment in beta. To choose in and activate a CA certificates for
your group or challenge, observe the
OpenAI Mutual TLS Beta Program
directions.

To authenticate API-key requests with a mutual TLS shopper certificates, present
the shopper certificates and personal key as separate PEM information. If certificates
chain help is enabled in your group, the certificates file should
comprise the leaf certificates first, adopted by any intermediate certificates.
Otherwise, use a shopper certificates signed instantly by an activated CA
certificates.

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

openai information listing

Both mTLS information have to be configured collectively. Keep the personal key in a
permission-restricted file; don’t put private-key contents instantly in command
arguments or atmosphere variables. The CLI doesn’t robotically choose an
mTLS endpoint, so configure OPENAI_BASE_URL or --base-url explicitly. HTTP
and SOCKS proxies stay supported, however HTTPS proxies are rejected to forestall
presenting the shopper certificates throughout the proxy’s personal TLS handshake.

For JSON enter values, @myfile.ext reads native file contents:

Binary add flags use plain paths. For instance, use information add --file "add area.txt" --purpose user_data.
Here, --file "@add area.txt" names an precise file beginning with @; it doesn’t increase one other file reference.
See working with files.

openai <command> --arg @abe.jpg

Files may also be handed inside JSON or YAML blobs:

openai <command> --arg '{picture: "@abe.jpg"}'
# Equivalent:
openai <command> <<YAML
arg:
  picture: "@abe.jpg"
YAML

When piping JSON or YAML from an untrusted supply, allow untrusted-stdin mode:

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

In this mode, values provided via stdin are handled as literal information: @,
@file://, and @information:// references in request our bodies, headers, and question
parameters don’t learn native information. File-upload parameters have to be supplied
explicitly as command-line flags. Explicit flags retain their regular file
conduct and take priority over values provided via stdin. Leave
OPENAI_UNTRUSTED_STDIN unset when utilizing trusted heredocs or different trusted
piped enter that deliberately references native information.

If you should cross a string literal that begins with an @ signal, you may
escape the @ signal to keep away from unintentionally passing a file.

openai <command> --username '@abe'

For JSON endpoints, the CLI software does filetype sniffing to find out whether or not the
file contents ought to be despatched as a string literal (for plain textual content information) or as a
base64-encoded string literal (for binary information). If you should explicitly ship
the file as both plain textual content or base64-encoded information, you should use
@file://myfile.txt (for string encoding) or @information://myfile.dat (for
base64-encoding). Note that absolute paths will start with @file:// or
@information://, adopted by a 3rd / (for instance, @file:///tmp/file.txt).

openai <command> --arg @information://file.txt

You can hyperlink the CLI towards a special model of the OpenAI Go SDK
for improvement functions utilizing the ./scripts/hyperlink script.

To hyperlink to a particular model from a repository (model generally is a department,
git tag, or commit hash):

./scripts/hyperlink github.com/org/repo@model

To hyperlink to an area copy of the SDK:

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

If you run the hyperlink script with none arguments, it’s going to default to ../openai-go.

Please share bug studies and have requests via GitHub issues.
Pull requests are restricted to repository collaborators; we don’t settle for pull requests from non-collaborators.
See CONTRIBUTING.md for the contribution coverage and improvement information.
For safety vulnerabilities, observe SECURITY.md.

Copyright 2026 OpenAI

This challenge is licensed underneath the Apache License 2.0.