openai-cli

Looking for the coding agent? Use Codex CLI.

Installation

Choose your operating system. Each setup installs all CLI commands and turns on automatic updates for normal interactive use.

macOS · Linux · Windows · When updates run

macOS

Using Homebrew and zsh, paste both lines together in Terminal. Use the same command for an older Homebrew installation.

brew update && brew install --cask openai/tools/openai &&
source "$(brew --prefix)/bin/openai-enable-updates.zsh"

Other shells and Homebrew troubleshooting · Install without Homebrew

Linux

On Debian, Ubuntu, or Fedora, download openai.sh. Open Bash or zsh in the download folder. Paste both lines together.

echo '3b94b2ac8e73bd16f3803ceea1ba5c08b1c80a3c9b27f75c5b8a9d4d76ff7e00  openai.sh' |
  sha256sum -c - && source ./openai.sh

Enter your password if sudo asks. Install over SSH · Other Linux distributions

Windows

1. Open the Windows installer.
2. Select Copy raw file.
3. Paste it into PowerShell without administrator privileges.

The installer downloads the matching ZIP and makes openai available in this terminal. Install with File Explorer

Explore commands

Run openai explore to search for commands in your own words. For example, to check a prompt's length without an API key, search for count tokens offline.

Highlight the command you want and press Enter to bring it back to your terminal.

Authentication

When you're ready to make an API request, run the setup guide for your shell.

openai help setup

For scripts, supply OPENAI_API_KEY through your environment or secret manager. Create an API key

Things to try

Send a request

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

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.

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. Command groups list their available commands. Each action shows its usage, required inputs, and relevant flags. When an action has an example, help shows it before the flag descriptions. To read about one flag, append it after -h, as in openai responses create -h --stream. For every flag's description, use openai help --all responses create. Existing colon-separated commands, such as openai admin:organization:usage completions, also work.

Admin requests

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

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.

--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.

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

For a complete request, responses create and chat completions create accept --request-file request.json. Use --request-file - to wait for a pipeline, including delayed producers. Run openai help piping for tokenizer, upload, and script examples.

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