Call the OpenAI REST API from your terminal or shell scripts. Generate images, upload
files, submit batches, and inspect API results without writing an application.

Things to try

These examples use an API key; see installation and
authentication below.

Generate an image and save it locally

openai images generate --prompt "A tiny orange robot watering a houseplant"

Images are saved to ~/Downloads/gpt-images/, and the command prints their paths.
Use --output-dir for an existing destination directory or --name for a filename.
Supported terminals can preview the result. See the image guide
for editing, model selection, and preview settings.

Upload a file and retrieve it later

openai files upload report.txt --purpose user_data
openai files get file-example
openai files download file-example --output downloaded-report.txt

Use your own local file and replace file-example with the ID returned by the upload.
See working with files for more examples.

Run requests in a batch

Submit a JSONL request file, then wait for the batch and download its results:

openai files upload requests.jsonl --purpose batch
openai batches create --input-file-id file-example \
  --endpoint /v1/responses --completion-window 24h
openai batches wait batch_example --output-dir ./results

Replace the file and batch IDs with the returned IDs. The batch guide
includes a sample requests.jsonl and explains result files and failed requests.

Export API data for a script

openai models list --format jsonl | jq '.id'
openai files list --format json > files.json

Choose --format json for a JSON document or --format jsonl for records.
The default output is readable text, even in pipes. The first example uses
jq.

Installation

Installing a prebuilt binary

Download the archive for your operating system and architecture from
GitHub Releases.
Binaries are available for macOS, Linux, and Windows. Extract the archive and
place openai (openai.exe on Windows) in a directory on your PATH.

Installing with Homebrew

brew install openai/tools/openai

Installing with Go

Requires Go 1.26 or later.

go install '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 base directory

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

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

The CLI checks for updates on eligible interactive runs; it never installs them
automatically. Set OPENAI_CLI_NO_UPDATE_CHECK=1 to disable checks and notices.
See update notices for details.

Authentication

Run the setup guide to enter your API key safely:

openai help setup

For scripts, supply OPENAI_API_KEY through your environment or secret manager.
Create a key in API settings.

Try a request:

openai responses create \
  --model gpt-5.5 \
  --input "Say this is a test"

Admin endpoints use OPENAI_ADMIN_KEY, a separate
admin API key.
For example, retrieve one day of organization usage:

openai admin organization usage completions \
  --start-time 1735689600 \
  --end-time 1735776000 \
  --bucket-width 1d

Usage

Commands follow the API's resources:

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

Browse commands and options with help. Help needs no API key or network connection.

openai --help
openai images generate --help
openai admin organization --help

openai help COMMAND and openai COMMAND --help show the same page.
Existing colon-separated commands, such as openai admin:organization:usage completions,
also work.

Output and errors

Successful JSON responses display readable text by default. Select a data format
explicitly when parsing results. Use --transform to extract fields with
GJSON syntax:

openai files get file-example --transform filename --raw-output

Errors go to stderr as readable summaries. Use --format-error json for API error
details, or --transform-error to extract error fields. Explicit --format json,
jsonl, raw, and yaml also apply to errors unless --format-error overrides
them; --format-error text restores summaries. API error details and --debug
logs can contain sensitive data: sanitize them before sharing.

Check the command's exit status before using redirected results; a failed request
can leave an incomplete output file. See reading command results
for list formats, streaming, binary downloads, and error behavior.

File input

Binary uploads take a plain path. JSON input flags can read a value from a local
file with @path:

openai files upload report.txt --purpose user_data
openai responses create --model gpt-5.5 --input @prompt.txt

Use OPENAI_UNTRUSTED_STDIN=1 when piping JSON or YAML from an untrusted source
so input cannot cause local file reads. In that mode, provide upload paths
explicitly as flags. See file arguments and encoding
for escaping literal @ values, JSON/YAML input, and text or base64 encoding.

Shell shortcuts

Set up shell completion to complete commands and file
paths. Command insertion lets you search examples
with Ctrl+X, then Tab and insert them without running them.

The first eligible interactive run saves image-picker Tab shortcuts for future
Bash, zsh, and fish sessions. Open a new terminal to use them. See
setup and removal for requirements and opt-out.
In PowerShell, press Enter after openai images generate to open the picker.

Guides

Task	Guide
Generate, edit, save, and preview images	Images
Upload and download files	Files
Submit batches and collect results	Batches
Generate speech and work with audio	Audio
Inspect and count tokens locally	Tokenizer
Test webhook handling	Webhooks
Parse results in scripts	Output formats
Configure headers, mTLS, and file input	CLI reference

Development

From a clone of this repository, run the CLI with:

./scripts/run --help

To test against another OpenAI Go SDK version, use ./scripts/link:

./scripts/link github.com/org/repo@version
./scripts/link ../path/to/openai-go

With no arguments, it uses ../openai-go. See CONTRIBUTING.md
for setup, checks, and repository structure.