OpenAI CLI

The authoritative CLI for the OpenAI REST API.

brew instal openai/tools/openai

To test or instal the CLI locally, you need Go type 1.26 or afterward installed.

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

Once you have run go install, the binary is placed in your Go bin directory:

• Default location: $HOME/go/bin (or $GOPATH/bin if GOPATH is set)
• Check your path: Run go env GOPATH to see the basis directory

If commands aren't established following installation, add the Go bin directory to your PATH:

# Add to your casing overview (.zshrc, .bashrc, etc.) export PATH="$PATH:$(go env GOPATH)/bin"

The archetypal eligible interactive openai run quietly saves depiction picker Tab shortcuts for forthcoming Bash, zsh, and seafood sessions. Open a new terminal to use them. See shortcut setup and removal for requirements and opt-out. PowerShell keeps normal Tab completion; media Enter after openai images create to open the picker.

Bare openai checks for newer stable releases whenever stdin, stdout, and stderr are terminals. It adds a plain-text notice below help, at most formerly all seven days. Explicit help, commands, completion, CI, and redirected streams skip the inspect entirely.

The notice includes an update command whenever the CLI can verify its facility method. Verified Homebrew installations use beer upgrade --cask openai/tools/openai. Go commands necessitate a verified binary, an accessible Go command, and an definitive matching GOBIN. Custom GOOS or GOARCH settings choose the facility guide instead. Go upgrades to important type 2 or afterward additionally choose the facility guide. Unknown installations obtain the installation-guide nexus instead. The CLI never installs updates automatically.

Checks use community GitHub publish metadata without API credentials, at most formerly daily. Checks regard HTTPS_PROXY and NO_PROXY, including their lowercase forms. Update finding waits at most 200 milliseconds. Failed checks remain silent. Package-manager preparedness can lag a new GitHub release. Set OPENAI_CLI_NO_UPDATE_CHECK=1 to disable checks and notices.

After cloning the git repository for this project, you can use the scripts/run manuscript to run the tool locally:

The CLI follows a resource-based command structure:

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

Standard API endpoints necessitate an API key:

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

Admin endpoints necessitate an admin API key:

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

Browse all collection alongside --help, for example openai admin --help or openai admin institution --help. Existing colon commands specified as openai admin:organization:usage completions continue to work.

Run openai to browse command groups by task, alongside descriptions for all group. Group assistance separates actions from nested command groups and lists all contiguous command. Help plant without an API key or network connection:

openai help setup # Enter your API key safely openai images create --help # Example and all depiction option openai help images create # The identical complete depiction help openai --help # Command groups and earth options

Add --help (or -h) to any command for its complete assistance page. openai assistance COMMAND shows the identical page. Command pages catalog earth options. Use openai --help for their complete descriptions. You can location --help following valid command options. The old assistance --all orthography prints immigration direction and the complete page. Command behavior, defaults, and output formats remain unchanged. Tab completion follows the identical collection command and supports assistance topics and document input paths. After upgrading, reload casing completion to allow the new file-path behavior. Older loaded completion scripts keep their former behavior until refreshed.

Enable command insertion to inhabit your command line from examples, setup guidance, and improvement commands. Ctrl+X, afterward Tab searches suggestions without operating them. Double Tab is an optional binding for Bash, zsh, and fish.

Successful JSON responses imprint readable content by default, including in pipes. Use --format json or --format jsonl in scripts that parse API data. See reading command results for extraction, binary output, and the range of readable presentation.

Upload a local document alongside an definitive purpose, inspect its metadata, afterward download its contents:

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

Replace file-example alongside the returned document ID. Upload takes a plain path, without an added @. create, retrieve, content, and their existing flags remain available. See working alongside files for literal filenames, output formats, and manuscript examples.

openai images create --prompt "A small orange robot" saves images to ~/Downloads/gpt-images/ and prints their paths, including in pipes. The CLI uses gpt-image-2.5-sunburst whenever preservation without an definitive example or legacy response format. Use --model for another exact ID, --name for a filename, or --output-dir for an existing directory. Existing records are kept. --format json returns API data without preservation or applying the CLI preset. images edit additionally saves new results during keeping origin files. images create-variation is former and no longer available. To create a variation, use images edit alongside a GPT Image example and a prompt. See image generation and saving for commands and defaults.

openai images preview "path/to/image.png" redisplays a saved depiction without an API request. Use openai images inline on or off to recall whether future saved images appear automatically. Per-command --inline auto, on or off overrides that setting. on additionally permits an depiction font in local Apple Terminal.

Errors imprint actionable summaries to stderr by default. Use --format-error json for first API error details, including unidentified sectors and SDK-reported stream error events. For those events, extraction paths contain the error envelope, for example --transform-error error.code. Explicit --format values json, jsonl, raw, and yaml additionally use to errors unless overridden by --format-error; an definitive --format-error car or content restores summaries. --transform-error extracts error data independently of prosperous output. Malformed or bare error bodies obtain a harmless diagnostic; HTTP position is included only whenever the SDK retains it. Summaries omit rejected values and petition URLs; explicit API error particulars can merge server-supplied delicate data.

• --api-key (can additionally be set alongside OPENAI_API_KEY env var)
• --admin-api-key (can additionally be set alongside OPENAI_ADMIN_KEY env var)
• --organization (can additionally be set alongside OPENAI_ORG_ID env var)
• --project (can additionally be set alongside OPENAI_PROJECT_ID env var)
• --webhook-secret (can additionally be set alongside OPENAI_WEBHOOK_SECRET env var)
• --mtls-client-cert-file (can additionally be set alongside OPENAI_MTLS_CLIENT_CERT_FILE env var)
• --mtls-client-key-file (can additionally be set alongside OPENAI_MTLS_CLIENT_KEY_FILE env var)
• --help - Show command row usage
• --debug - Enable debug logging. This includes HTTP request/response particulars and bodies; do not portion debug logs if they may merge delicate payloads.
• --version, -v - Show the CLI version
• --base-url - Use a tradition API backend URL. HTTPS is required apart from for localhost or literal loopback IP addresses specified as 127.0.0.1 and ::1. This additionally applies to OPENAI_BASE_URL; distant HTTP backends must allow HTTPS.
• --header, -H - Add a literal petition header as Name: Value; reiterate for multiple headers
• --format - Change the output format (auto, text, explore, json, jsonl, pretty, raw, yaml); car selects readable content unless extracting data
• --format-error - Change the stderr error format (auto, text, explore, json, jsonl, pretty, raw, yaml); car selects readable summaries unless extracting error data
• --transform - Transform the data output using GJSON syntax
• --transform-error - Transform the error output using GJSON syntax

Use --header or -H before or following a asset command:

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

Values are literal: commas and colons are preserved, and @ prefixes do not read files. Surrounding spaces and tabs are trimmed from values. -H 'X-Example:' sends an bare value. If a name is repeated, the final value wins despite of case, overriding default and endpoint-specific headers. Headers managed by the HTTP transport, specified as Host and Content-Length, keep the transport's behavior. Supplied header values are hidden in assistance and redacted in debug logs.

For credential-bearing headers, have a concealed director or trusted launcher set OPENAI_CUSTOM_HEADERS immediately in the CLI's environment. This keeps credentials out of command arguments and avoids typing literal secrets into casing history. The changeable accepts one Name: Value admission per line. For example, with non-sensitive values:

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

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

Mutual TLS is currently in beta. To opt in and activate a CA certificate for your institution or project, prosecute the OpenAI Mutual TLS Beta Program instructions.

To authenticate API-key requests alongside a mutual TLS client certificate, provide the client certificate and personal key as distinct PEM files. If certificate chain assistance is enabled for your organization, the certificate document must contain the leaf certificate first, followed by any intermediate certificates. Otherwise, use a client certificate signed immediately by an activated CA certificate.

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 records list

Both mTLS records must be configured together. Keep the personal key in a permission-restricted file; do not put private-key contents immediately in command arguments or surroundings variables. The CLI does not automatically choose an mTLS endpoint, so configure OPENAI_BASE_URL or --base-url explicitly. HTTP and SOCKS proxies remain supported, but HTTPS proxies are rejected to prevent presenting the client certificate during the proxy's own TLS handshake.

For JSON input values, @myfile.ext says local document contents:

Binary upload flags use plain paths. For example, use records upload --file "upload space.txt" --purpose user_data. Here, --file "@upload space.txt" names an genuine document starting alongside @; it does not develop another document reference. See working alongside files.

openai <command> --arg @abe.jpg

Files can additionally be passed inner JSON or YAML blobs:

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

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

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

In this mode, values supplied through stdin are treated as literal data: @, @file://, and @data:// references in petition bodies, headers, and query parameters do not peruse local files. File-upload parameters must be provided explicitly as command-line flags. Explicit flags keep their normal file behavior and obtain precedence complete values supplied through stdin. Leave OPENAI_UNTRUSTED_STDIN unset whenever using trusted heredocs or another trusted piped input that intentionally references local files.

If you need to continue a cord literal that starts alongside an @ sign, you can escape the @ sign to evade accidentally passing a file.

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

For JSON endpoints, the CLI tool does filetype sniffing to decide whether the file contents have to be sent as a cord literal (for plain content files) or as a base64-encoded cord literal (for binary files). If you need to explicitly send the document as either plain content or base64-encoded data, you can use @file://myfile.txt (for cord encoding) or @data://myfile.dat (for base64-encoding). Note that complete paths volition commencement alongside @file:// or @data://, followed by a third / (for example, @file:///tmp/file.txt).

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

You can nexus the CLI against a distinct type of the OpenAI Go SDK for betterment purposes using the ./scripts/link script.

To nexus to a particular type from a repository (version can be a branch, git tag, or commit hash):

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

To nexus to a local copy of the SDK:

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

If you run the nexus manuscript without any arguments, it volition default to ../openai-go.

Please portion bug reports and characteristic requests through GitHub issues. Pull requests are constricted to repository collaborators; we do not obtain drag requests from non-collaborators. See CONTRIBUTING.md for the contribution guideline and betterment guide. For safety vulnerabilities, prosecute SECURITY.md.

Copyright 2026 OpenAI

This project is licensed under the Apache License 2.0.