OpenAI CLI

The official command-line tool for the OpenAI REST API.

Install · CLI reference · Guides

Looking for the coding agent? Use Codex CLI.

Installation

macOS · Linux · Windows

macOS

With Homebrew and zsh, paste both lines together in Terminal. This installs the CLI, enables automatic updates, and makes Explore selections editable at your prompt.

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

Use the same paste for an older Homebrew installation. When automatic updates run.

Terminal says “no such file” for the update helper

Your Homebrew package lacks the setup helper. You can use the installed CLI now, even if another copy comes first.

"$(brew --prefix)/bin/openai" --help

Repeat the installation once Homebrew offers a version with the helper. Check the installed CLI version.

Using another shell? Install with Homebrew. Without Homebrew, use the macOS ZIP.

Linux

For automatic updates, install the release archive. It requires GitHub CLI (gh). If you prefer a Debian or RPM package, install it with your package manager. Upgrade it manually.

Windows

Install the Windows ZIP. To upgrade, download and extract a newer ZIP.

Authentication

Check the installation without an API key.

openai --help

To make API requests, follow the instructions this command prints for your shell.

openai help setup

On Windows, use .\openai.exe from the extracted directory. For scripts, supply OPENAI_API_KEY through your environment or secret manager. Create an API key

Use the CLI from a coding agent

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.

Agent	Current project	All projects for this user
Codex	.agents/skills/	~/.agents/skills/
Claude Code	.claude/skills/	~/.claude/skills/

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

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. 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 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
Create vector stores, upload files, and search	Vector stores
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

Tip

Managing OpenAI resources with Terraform? Use the official OpenAI Terraform provider to manage projects, service accounts, rate limits, and other supported resources as infrastructure as code.

Development

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.

Contributing

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.

License

Copyright 2026 OpenAI

This project is licensed under the Apache License 2.0.