OpenAI CLI

What it claims

openai is OpenAI's Go command-line client for the REST API, licensed under Apache License 2.0. It covers images, files, batches, the Responses API and admin usage. The README positions it against Codex CLI (codex): openai is for calling a specific API or scripting API operations. Codex is a coding agent that reads and edits code. Commands mirror API resources as openai <resource> [subresource...] <command> [flags...]. Older colon-separated forms such as openai admin:organization:usage completions still work.

How to use it

Install with Homebrew, go install (requires Go 1.26 or later, binary lands in $(go env GOPATH)/bin), or a release archive for macOS, Linux or Windows:

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

openai help setup walks through entering an API key. Scripts should supply OPENAI_API_KEY from the environment or a secret manager. Admin endpoints need a separate OPENAI_ADMIN_KEY. Help pages need no key or network connection.

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

A batch runs as upload, create, then a blocking wait that downloads 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

openai images generate --prompt "..." saves to ~/Downloads/gpt-images/ by default and prints the paths. --output-dir and --name override this.

Output defaults to readable text even when piped, so scripts must pass --format json, jsonl, yaml or raw. --transform takes GJSON paths:

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

Errors go to stderr as text summaries. --format-error json or --transform-error give structured error details. An explicit --format also applies to errors unless --format-error overrides it. JSON input flags read file contents with @path, as in --input @prompt.txt. Binary uploads take a plain path.

Shell completion also offers command insertion: Ctrl+X, then Tab, searches examples without running them.

Limits

• A failed request can leave an incomplete output file. Check the exit status before using redirected results.
• @path expansion means piped JSON or YAML can trigger local file reads. Set OPENAI_UNTRUSTED_STDIN=1 for untrusted input and pass upload paths as flags.
• API error details and --debug logs can contain sensitive data and need sanitizing before they are shared.
• Interactive runs check for updates but never install them. OPENAI_CLI_NO_UPDATE_CHECK=1 turns off the checks and notices.
• The first eligible interactive run writes image-picker Tab shortcuts into Bash, zsh and fish sessions. An opt-out is documented separately.
• Pull requests are accepted only from repository collaborators. Outside users can file GitHub issues.
• To build against a different openai-go SDK version, use ./scripts/link. With no arguments it uses ../openai-go.
• For managing projects, service accounts and rate limits as infrastructure, the README points to the official OpenAI Terraform provider instead.