OpenAI 发布官方 CLI 工具 支持 Homebrew 与 Go 安装

The official CLI for the OpenAI REST API.

Installation

Installing with Homebrew

brew install openai/tools/openai

Installing with Go

To test or install the CLI locally, you need Go version 1.26 or later installed.

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"

The first eligible interactive openai run quietly saves image picker Tab shortcuts for future Bash, zsh, and fish sessions. Open a new terminal to use them. See shortcut setup and removal for requirements and opt-out. PowerShell keeps normal Tab completion; press Enter after openai images generate to open the picker.

Update notices

Bare openai checks for newer stable releases when stdin, stdout, and stderr are terminals. It adds a plain-text notice below help, at most once every seven days. Explicit help, commands, completion, CI, and redirected streams skip the check entirely.

The notice includes an update command when the CLI can verify its installation method. Verified Homebrew installations use brew upgrade --cask openai/tools/openai. Go commands require a verified binary, an available Go command, and an explicit matching GOBIN. Custom GOOS or GOARCH settings select the installation guide instead. Go upgrades to major version 2 or later also select the installation guide. Unknown installations receive the installation-guide link instead. The CLI never installs updates automatically.

Checks use public GitHub release metadata without API credentials, at most once daily. Checks respect HTTPS_PROXY and NO_PROXY, including their lowercase forms. Update discovery waits at most 200 milliseconds. Failed checks remain silent. Package-manager availability can lag a new GitHub release. Set OPENAI_CLI_NO_UPDATE_CHECK=1 to disable checks and notices.

Running Locally

After cloning the git repository for this project, you can use the scripts/run script to run the tool locally:

./scripts/run args...

Usage

The CLI follows a resource-based command structure:

openai <resource> [subresource...] <command> [flags...]

Standard API endpoints require an API key:

export OPENAI_API_KEY="sk-..."

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

Admin endpoints require an admin API key:

export OPENAI_ADMIN_KEY="sk-admin-..."

openai admin organization usage completions \
  --start-time 1735689600 \
  --end-time 1735776000 \
  --bucket-width 1d

Browse each group with --help, for example openai admin --help or openai admin organization --help. Existing colon commands such as openai admin:organization:usage completions continue to work.

Run openai to browse command groups by task, with descriptions for each group. Group help separates actions from nested command groups and lists every immediate command. Help works without an API key or network connection:

openai help setup                  # Enter your API key safely
openai images generate --help      # Example and every image option
openai help images generate        # The same complete image help
openai --help                      # Command groups and global options

Add --help (or -h) to any command for its complete help page. openai help COMMAND shows the same page. Command pages list global options. Use openai --help for their full descriptions. You can place --help after valid command options. The old help --all spelling prints migration guidance and the complete page. Command behavior, defaults, and output formats remain unchanged. Tab completion follows the same group order and supports help topics and file input paths. After upgrading, reload shell completion to enable the new file-path behavior. Older loaded completion scripts keep their previous behavior until refreshed.

Enable command insertion to fill your command line from examples, setup guidance, and recovery commands. Ctrl+X, then Tab searches suggestions without running them. Double Tab is an optional binding for Bash, zsh, and fish.

Successful JSON responses print readable text by default, including in pipes. Use --format json or --format jsonl in scripts that parse API data. See reading command results for extraction, binary output, and the scope of readable presentation.

Upload a local file with an explicit purpose, inspect its metadata, then download its contents:

openai files upload "upload space.txt" --purpose user_data
openai files get file-example
openai files download file-example --output "downloaded copy.txt"
openai files download file-example > copy.txt

Replace file-example with the returned file ID. Upload takes a plain path, without an added @. create, retrieve, content, and their existing flags remain available. See working with files for literal filenames, output formats, and script examples.

openai images generate --prompt "A tiny orange robot" saves images to ~/Downloads/gpt-images/ and prints their paths, including in pipes. The CLI uses gpt-image-2.5-sunburst when saving without an explicit model or legacy response format. Use --model for another exact ID, --name for a filename, or --output-dir for an existing directory. Existing files are kept. --format json returns API data without saving or applying the CLI preset. images edit also saves new results while keeping source files. images create-variation is retired and no longer available. To create a variation, use images edit with a GPT Image model and a prompt. See image generation and saving for commands and defaults.

openai images preview "path/to/image.png" redisplays a saved image without an API request. Use `openai images inline o

（注：更多技术实现细节与完整 API 文档请查阅原项目 README）