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

Use OpenAI CLI to call the OpenAI REST API from terminal commands, scripts, files, and admin workflows.

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.
  • Searches commands by task and counts tokens locally with openai explore and openai tokenizer count.
  • Browses batches and manages searchable vector stores from interactive terminal workspaces.

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.

OpenAI CLICodex CLI
Main purposeDirect OpenAI API calls.Agentic coding tasks.
Primary commandopenaicodex
TasksAPI requests, scripts, file operations, admin usage checks.Repository inspection, code edits, code review, terminal coding tasks.
AuthenticationAPI key or admin API key.ChatGPT sign-in or API key.
AgentNo built-in coding agent.Runs as a local coding agent.
OutputReadable text, structured formats, GJSON transforms.Agent sessions, code changes, command execution.

How to Use OpenAI CLI

Install the CLI

macOS (Homebrew and zsh): Run both lines together in Terminal to install OpenAI CLI and enable automatic updates:

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

Linux (Debian, Ubuntu, Fedora): Download the official release installer in Bash or zsh and run it in the same shell. Enter your password if the installer requests sudo access:

curl -fL -o openai.sh https://github.com/openai/openai-cli/releases/latest/download/openai.sh
source ./openai.sh

Windows (PowerShell): Open the official Windows installation script on GitHub and select Copy raw file. Open PowerShell as a regular user, paste the copied script, and press Enter. It downloads the appropriate Windows ZIP and makes openai available in that PowerShell session.

Go: With Go installed, build the CLI from source:

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

Explore Commands and Manage API Data

Run openai explore to find commands by task before setting an API key. For API data, openai batches browse lets you inspect batch jobs, results, and errors. openai vector-stores manage lets you attach files, monitor indexing, and search stored content.

openai explore
openai tokenizer count --help
openai batches browse
openai vector-stores manage

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'

Interactive List Browsing and Structured Inputs

List commands open an interactive browser when both input and output are connected to a terminal. For unattended terminal scripts, add --browse=false to prevent the command from waiting for navigation. Arguments with a matching -structured flag treat plain text literally; use the structured flag to pass JSON or YAML.

# Continue without interactive list browsing
openai models list --browse=false
# Supply a JSON file as structured Responses input
openai responses create --model gpt-5.5 --input-structured @messages.json

Pass Local Files

Use @filename for file inputs. For arguments that offer a matching -structured flag, select that flag when passing JSON or YAML with embedded file references. 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

SyntaxPurpose
openai [resource] <command> [flags...]Runs a command against an API resource.
openaiShows the starting guide.
openai help setupShows API key setup guidance.
openai [resource] <command> --helpShows command help and common inputs.
openai help --allShows every command and global option.
openai exploreSearches commands by task in an interactive picker.
openai --versionShows the installed CLI version.

Installation

MethodCommandRequirement
Homebrewbrew install --cask openai/tools/openaiHomebrew installed; zsh for automatic updates.
Gogo install 'github.com/openai/openai-cli/cmd/openai@latest'Go installed.
Local repository./scripts/run args...Cloned repository.

Environment Variables

Environment VariablePurpose
OPENAI_API_KEYStandard API authentication.
OPENAI_ADMIN_KEYAdmin endpoint authentication.
OPENAI_ORG_IDOrganization selection.
OPENAI_PROJECT_IDProject selection.
OPENAI_WEBHOOK_SECRETWebhook verification.
OPENAI_CUSTOM_HEADERSCustom request headers supplied through the environment.
OPENAI_MTLS_CLIENT_CERT_FILEmTLS client certificate file.
OPENAI_MTLS_CLIENT_KEY_FILEmTLS private key file.
OPENAI_UNTRUSTED_STDINDisables local file expansion for piped request data when set to 1.

Global Flags

FlagPurpose
--api-keySets the standard API key.
--admin-api-keySets the admin API key.
--organizationSets the organization.
--projectSets the project.
--webhook-secretSets the webhook secret.
--base-urlUses a custom API backend URL.
--header, -HAdds a literal request header.
--formatChanges successful output format.
--format-errorChanges error output format.
--transformExtracts successful output with GJSON syntax.
--transform-errorExtracts error output with GJSON syntax.
--debugEnables HTTP request and response debug logging.
--version, -vShows the CLI version.

Output Formats

FormatUse
autoUses readable text by default and adapts when extracting data.
textReadable text output.
exploreExplorer-style output.
jsonJSON output.
jsonlJSON Lines output.
prettyFormatted structured output.
rawRaw response data.
yamlYAML output.

File Argument Syntax

SyntaxPurpose
@myfile.extPasses a local file as an argument.
'\@abe'Sends a literal string that begins with @.
@file://myfile.txtSends file contents as text.
@data://file.datSends file contents as base64 data.
@file:///tmp/file.txtUses an absolute file path with text encoding.
@data:///tmp/file.datUses an absolute file path with base64 encoding.

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. The PowerShell installer downloads the Windows ZIP and makes the openai command available in that terminal session.

Related Resources

Last Updated: Nov 12, 2026

Leave a Reply

Your email address will not be published. Required fields are marked *

Get the latest & top AI tools sent directly to your email.

Subscribe now to explore the latest & top AI tools and resources, all in one convenient newsletter. No spam, we promise!