Looking for the coding agent? Use Codex CLI.

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

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

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

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

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.

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

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

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.

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

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

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.

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.

The optional OpenAI CLI skill helps a shell agent choose API commands and interpret their output. Install the CLI in the environment where the agent runs.

From your project, use GitHub CLI to install the skill from a tagged release that includes it:

gh skill install openai/openai-cli openai-cli --agent codex --scope project

Choose your agent with --agent. Options include claude-code, cursor, gemini-cli, and github-copilot. Run gh skill install --help for the full list. Use --scope user to share the skill across your projects.

For an unreleased checkout, use its local path instead:

gh skill install /path/to/openai-cli openai-cli --from-local --agent codex --scope project

For manual installation, copy the entire skills/openai-cli folder into the appropriate skills directory.

Start a new agent session in the target project. For example, ask “Upload requests.jsonl to OpenAI for a future batch.”

To install from source, follow the Go installation instructions.

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.