The OpenAI CLI is the official command-line interface for the OpenAI REST API, written in Go and published by OpenAI as an open-source project. It enables your terminal to access OpenAI endpoints for text generation, file management, audio, images, and organization-level usage reporting.
You can use the CLI to send requests, inspect responses, and pull admin-level usage data from a shell. It can be useful for testing model behavior, scripting automated API workflows, and exploring endpoints before embedding them into a full application.
Features
- Accepts text input and file arguments for any supported API endpoint.
- Outputs results in seven configurable formats:
auto,explore,json,jsonl,pretty,raw, andyaml. - Supports GJSON syntax for transforming output data directly in the terminal.
- Passes files to the API using
@filenamesyntax, with automatic filetype detection for text versus binary. - Accepts both a standard API key and a separate admin API key for organization-level endpoints.
- Debug mode logs full HTTP request and response bodies.
- Supports a custom base URL for testing against alternate API backends.
- All credentials load from environment variables or inline flags.
OpenAI CLI vs OpenAI Codex CLI
OpenAI CLI and Codex CLI solve different developer problems. OpenAI CLI is the better fit when you want direct API access from shell commands. Codex CLI is the better fit when you want an AI coding agent that can inspect a project, edit code, and run terminal workflows.
| Category | OpenAI CLI | OpenAI Codex CLI |
|---|---|---|
| Main purpose | API calls from the terminal. | Agentic coding from the terminal. |
| Best use case | Scripts, API requests, admin usage checks, file-based API workflows. | Code edits, repository inspection, code review, and terminal coding workflows. |
| Primary command | openai | codex |
| Installation | Homebrew or Go install. | npm, Homebrew cask, or release binary. |
| Authentication | API key or admin API key. | ChatGPT sign-in or API-key setup. |
| Coding agent behavior | No built-in repository agent workflow. | Runs as a local coding agent. |
| Output control | Output formats and GJSON transforms. | Agent sessions, code changes, and local workflow control. |
| Best reader choice | Use it to call OpenAI APIs directly. | Use it to work on code with an AI agent. |
How to Use It
1. Install OpenAI CLI with Homebrew:
brew install openai/tools/openai2. OR install OpenAI CLI with Go:
go install 'github.com/openai/openai-cli/cmd/openai@latest'Go places the binary in the Go bin directory. The default location is $HOME/go/bin, unless GOPATH changes the location.
go env GOPATHA missing openai command usually means the Go bin directory needs PATH access.
export PATH="$PATH:$(go env GOPATH)/bin"3. Set an OpenAI API key:
export OPENAI_API_KEY="sk-..."4. Run a Responses API request:
openai responses create \
--input "Say this is a test" \
--model gpt-5.55. Set an admin API key:
export OPENAI_ADMIN_KEY="sk-admin-..."6. Query organization usage:
openai admin:organization:usage completions \
--start-time 1735689600 \
--end-time 1735776000 \
--bucket-width 1d7. Read command-specific help:
openai --helpopenai responses create --help8. Pass a file as an argument
openai <command> --arg @abe.jpg9. Pass a file inside JSON:
openai <command> --arg '{image: "@abe.jpg"}'10. Pass a file inside YAML:
openai <command> <<YAML
arg:
image: "@abe.jpg"
YAML11. Escape an @ string:
openai <command> --username '\@abe'12. Use explicit file encoding:
openai <command> --arg @file://myfile.txtThe @data:// syntax sends a file as base64-encoded data.
openai <command> --arg @data://file.txt13. Run the project locally:
./scripts/run args...Technical Reference
Basic Commands
| Syntax | Purpose |
|---|---|
openai [resource] <command> [flags...] | Runs a command against an API resource. |
openai --help | Shows top-level command help. |
openai [resource] <command> --help | Shows command-specific help. |
openai --version | Shows the installed CLI version. |
openai -v | Shows the installed CLI version. |
Installation Commands
| Method | Command | Requirement |
|---|---|---|
| Homebrew | brew install openai/tools/openai | Homebrew installed. |
| Go | go install 'github.com/openai/openai-cli/cmd/openai@latest' | Go 1.25 or later. |
| Local repository run | ./scripts/run args... | Cloned project repository. |
Authentication Variables
| Environment variable | Required | Default value | Purpose |
|---|---|---|---|
OPENAI_API_KEY | No | null | Standard API authentication. |
OPENAI_ADMIN_KEY | No | null | Admin endpoint authentication. |
OPENAI_ORG_ID | No | null | Organization selection. |
OPENAI_PROJECT_ID | No | null | Project selection. |
OPENAI_WEBHOOK_SECRET | No | null | Webhook verification. |
Global Flags
| Flag | Environment variable | Purpose |
|---|---|---|
--api-key | OPENAI_API_KEY | Sets the standard API key. |
--admin-api-key | OPENAI_ADMIN_KEY | Sets the admin API key. |
--organization | OPENAI_ORG_ID | Sets the organization. |
--project | OPENAI_PROJECT_ID | Sets the project. |
--webhook-secret | OPENAI_WEBHOOK_SECRET | Sets the webhook secret. |
--help | None | Shows command-line usage. |
--debug | None | Enables HTTP request and response debug logging. |
--version | None | Shows the CLI version. |
-v | None | Shows the CLI version. |
--base-url | None | Uses a custom API backend URL. |
--format | None | Changes the normal output format. |
--format-error | None | Changes the error output format. |
--transform | None | Transforms normal output with GJSON syntax. |
--transform-error | None | Transforms error output with GJSON syntax. |
Output Formats
| Format | Use |
|---|---|
auto | Lets the CLI choose an output format. |
explore | Uses an exploratory output view. |
json | Outputs JSON. |
jsonl | Outputs JSON Lines. |
pretty | Outputs readable formatted text. |
raw | Outputs raw response data. |
yaml | Outputs YAML. |
File Argument Syntax
| Syntax | Purpose |
|---|---|
@myfile.ext | Passes a local file as an argument. |
@abe.jpg | Passes an image file. |
{image: "@abe.jpg"} | Passes a file reference inside JSON-style input. |
'\@abe' | Sends a literal string that starts with @. |
@file://myfile.txt | Sends a file as plain text. |
@data://file.txt | Sends a file as base64-encoded data. |
@file:///tmp/file.txt | Sends an absolute path as plain text. |
@data:///tmp/file.dat | Sends an absolute path as base64-encoded data. |
Development Linking Commands
The ./scripts/link script links the CLI against another OpenAI Go SDK version during development.
./scripts/link github.com/org/repo@versionA local SDK copy can also serve as the linked target.
./scripts/link ../path/to/openai-goThe script defaults to ../openai-go when no argument is supplied.
./scripts/linkAlternatives and Related Resources
- Free AI-powered CLI Tools: Browse AI tools that run from the command line.
- OpenAI CLI Documentation: Open the command guide for authentication, use cases, and terminal workflow details.
- OpenAI Codex GitHub Repository: Open the Codex repository for terminal coding agent installation and release downloads.
- OpenAI Codex Commands Cheat Sheet: Compare Codex CLI commands, flags, config keys, MCP usage, and coding workflows.
- Best CLI AI Coding Agents: Compare Codex with other terminal-based AI coding agents.
- Free AI Tools for Developers: Browse developer-focused AI tools for coding, debugging, documentation, and app building.
Pros
- Open-source under OpenAI.
- Installs via Homebrew or Go.
- Seven output formats, including JSONL and YAML.
- GJSON support for inline output transformation.
- Debug mode for full HTTP request inspection.
- Supports both standard and admin API keys.
Cons
- No GUI or browser interface.
- Not a coding agent.
- Does not read or write local files on its own.
- Admin endpoints need a separate admin API key.
FAQs
Q: Is the OpenAI CLI free?
A: The CLI is free and open-source. API usage is billed per token to your OpenAI account.
Q: Does the OpenAI CLI require a signup?
A: An OpenAI account and a valid API key from the OpenAI platform are required.
Q: What is the difference between the OpenAI CLI and the OpenAI Codex CLI?
A: The OpenAI CLI is an API wrapper for sending requests, managing resources, and pulling usage stats from the terminal. The Codex CLI is an agentic coding tool that reads and edits files on your local machine in response to natural language prompts. They are separate projects with different purposes.
Q: Does the OpenAI CLI run on Windows?
A: The Go-based install works on any platform Go supports, including Windows, macOS, and Linux. The Homebrew method is macOS and Linux only.
