OpenAI CLI: Run OpenAI API Calls from Your Terminal (Official)

OpenAI CLI is OpenAI’s official, open-source command-line client for the OpenAI REST API.

It lets you call API resources directly from a terminal with the openai command, including Responses, files, audio, images, and organization-level admin endpoints.

After installation, you can authenticate with an API key and run requests from shell scripts or interactive terminal sessions.

The CLI returns readable terminal output, exposes structured formats for scripts, accepts file arguments, transforms response data, passes custom headers, and accesses admin endpoints with admin credentials.

Features

• Runs OpenAI REST API requests from the terminal with the openai command.
• Uses a resource-based command structure: openai [resource] <command> [flags...].
• Shows readable terminal output by default and returns json, jsonl, yaml, raw, and other structured formats for scripts.
• Streams readable Responses and audio results in terminal sessions and pipes.
• Uses GJSON syntax with --transform and --transform-error to extract response data.
• Passes local files with @filename, @file://, and @data:// syntax.
• Passes custom request headers through --header, -H, and OPENAI_CUSTOM_HEADERS.
• Uses OPENAI_UNTRUSTED_STDIN to prevent piped JSON or YAML from reading local file references.
• Saves generated and edited images and can preview saved images in terminals.

OpenAI CLI vs OpenAI Codex CLI

OpenAI CLI sends requests to OpenAI API resources from shell commands. Codex CLI works as a coding agent for repository inspection, code changes, review, and terminal tasks.

How to Use OpenAI CLI

Install the CLI

Install OpenAI CLI with Homebrew, or use Go 1.26 or later:

# Homebrew
brew install openai/tools/openai
# Go
go install 'github.com/openai/openai-cli/cmd/openai@latest'

Set Your API Key

Set OPENAI_API_KEY for the shell session that will run the CLI:

# macOS / Linux
export OPENAI_API_KEY="sk-..."
# Windows PowerShell
$env:OPENAI_API_KEY="sk-..."
# Windows Command Prompt
set OPENAI_API_KEY=sk-...

Run a Responses API Request

A basic Responses API request uses the responses create command:

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

Open Command Help

Built-in help works locally and shows setup guidance, common command inputs, or the complete command list:

openai help setup
openai responses create --help
openai help --all

Output and File Input

Format and Transform Output

Successful JSON responses appear as readable text by default. Scripts can request structured output with --format, and GJSON expressions can extract fields from normal or error output.

openai --format json models list
openai --format jsonl <resource> <command>
openai <resource> <command> --transform '<gjson-path>'
openai <resource> <command> --transform-error 'error.code'

Pass Local Files

Use @filename for normal file input. File references also work inside JSON or YAML. Use @file:// for text encoding and @data:// for base64 encoding.

openai <command> --arg @abe.jpg
openai <command> --arg '{image: "@abe.jpg"}'
openai <command> <<YAML
arg:
  image: "@abe.jpg"
YAML
openai <command> --arg @file://myfile.txt
openai <command> --arg @data://file.dat

Protect Untrusted Piped Input

Set OPENAI_UNTRUSTED_STDIN=1 when piped JSON or YAML comes from an untrusted source. Values from stdin are handled as literal data, and explicit file-upload flags keep their normal file behavior.

untrusted-producer | OPENAI_UNTRUSTED_STDIN=1 openai <command> --file ./upload.txt

Images in the Terminal

Image commands save completed results to disk. Your terminal can preview saved images, openai images preview can redisplay a local image, and --partial-images can show progress previews during generation or editing.

# Generate and save an image
openai images generate --prompt "A tiny orange robot"
# Save the inline-preview preference and redisplay a saved image
openai images inline on
openai images preview "path/to/image.png"
# Show two partial progress previews
openai images generate \
  --prompt "A tiny orange robot" \
  --partial-images 2

Authentication and Advanced Options

Admin API Key

Organization-level admin endpoints use OPENAI_ADMIN_KEY or the matching admin-key flag.

export OPENAI_ADMIN_KEY="sk-admin-..."
openai admin:organization:usage completions \
  --start-time 1735689600 \
  --end-time 1735776000 \
  --bucket-width 1d

Custom Request Headers

Pass literal request headers with --header or -H. Put credential-bearing custom headers in OPENAI_CUSTOM_HEADERS to keep them out of shell command history.

openai --header 'X-Trace-ID: example-123' models list \
  -H 'X-Client-Label: local,manual'

Mutual TLS

Organizations enrolled in OpenAI’s mutual TLS beta can authenticate API-key requests with a client certificate and private key stored in two PEM files.

Set both file variables and select the mTLS endpoint with OPENAI_BASE_URL or --base-url. Keep the private key in a permission-restricted file. HTTP and SOCKS proxies work with mTLS; HTTPS proxies are rejected.

export OPENAI_MTLS_CLIENT_CERT_FILE=/run/secrets/openai/client-chain.pem
export OPENAI_MTLS_CLIENT_KEY_FILE=/run/secrets/openai/client.key
export OPENAI_BASE_URL=https://mtls.api.openai.com/v1
openai files list

OpenAI CLI Quick Reference

Basic Commands

Installation

Environment Variables

Global Flags

Output Formats

File Argument Syntax

Pros

• Official OpenAI CLI.
• Apache 2.0 open-source license.
• Readable and structured output modes.
• File arguments and GJSON transforms.
• Standard and admin API authentication.
• Terminal image saving and previews.

Cons

• No built-in coding agent.
• OpenAI API usage is billed separately.
• Debug output can contain sensitive request or response data.

FAQs

Q: Is the OpenAI CLI free?
A: The CLI is open-source under the Apache 2.0 license. OpenAI API requests are billed through your API account according to the endpoints and models you use.

Q: Do I need a ChatGPT subscription to use the OpenAI CLI?
A: The CLI uses OpenAI API credentials. API access and billing are handled through your OpenAI API account.

Q: Does the OpenAI CLI run on Windows?
A: Yes. OpenAI provides Windows release builds, and the Go installation method can install the CLI on Windows. Homebrew is mainly used on macOS and Linux.

Recent OpenAI CLI Updates

• v1.28.0, September 27, 2026: Added progress previews for image generation and editing when partial images are requested.
• v1.27.0, September 26, 2026: Added saved-image preview commands and persistent inline preview settings.
• v1.26.0, September 26, 2026: Added terminal previews for completed saved images.
• v1.19.0 to v1.23.0: Added readable default results, readable streaming for Responses and audio, and improved terminal result presentation.

Related Resources

• 100+ Best, Open-source & AI-powered CLI Tools: Find more command-line AI tools and developer utilities.
• OpenAI CLI Documentation: API commands, authentication, and CLI usage.
• OpenAI CLI GitHub Repository: Source code, releases, installation files, and license.
• OpenAI Codex Commands Cheat Sheet: Codex CLI commands, flags, config keys, MCP usage, and coding tasks.
• Best CLI AI Coding Agents: Compare CLI coding agents for repository and code work.
• Free AI Tools for Developers: Developer-focused AI tools for coding, debugging, documentation, and app development.