gem-hunter

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.

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

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.

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.

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.

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.

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.

brew install openai/tools/openai

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"

Supported self-managed release installations prepare automatic updates during eligible interactive runs. Package-manager and Go installations retain update notices and their existing installation ownership. Set OPENAI_CLI_NO_AUTO_UPDATE=1 to disable automatic installation, or OPENAI_CLI_NO_UPDATE_CHECK=1 to disable all update checks. See automatic updates for installation requirements, exact-version pins, and activation behavior.

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

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.

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.

--debug adds per-attempt HTTP timing. Add --debug-body for redacted JSON previews or --debug-sse --debug-event-timing for bounded stream diagnostics. See HTTP debugging for capture limits and timing boundaries.

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.

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.

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.

scripts/run is a development helper for running the CLI from a cloned checkout:

./scripts/run --help

See the development instructions for its dependency, credential, path, and exit-status behavior.

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.

Please share bug reports and feature requests through GitHub issues. Pull requests are limited to repository collaborators; we do not accept pull requests from non-collaborators. See CONTRIBUTING.md for the contribution policy and development guide. See the security model for trust boundaries. For security vulnerabilities, follow SECURITY.md.

Copyright 2026 OpenAI

This project is licensed under the Apache License 2.0.