Voozh

👁 openai-cli

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.

Visit OpenAI CLI

Features

Runs OpenAI REST API requests from the terminal with the openai command.
Uses a resource-based command structure: openai [resource] <command> [flags...].
Accepts text input and file arguments for supported API endpoints.
Outputs results in seven configurable formats: auto, explore, json, jsonl, pretty, raw, and yaml.
Uses GJSON syntax to transform response data directly in terminal output.
Passes files to the API with @filename syntax and automatic filetype detection for text and binary input.
Sends files as plain text with @file:// or base64-encoded data with @data://.
Accepts a standard API key for normal endpoints and an admin API key for admin endpoints.
Loads credentials and project settings from environment variables or inline flags.
Uses debug mode to show HTTP request and response details. You should not share debug logs if they contain private payloads or credentials.
Supports a custom base URL for alternate API backends.

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	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/openai

2. You can also 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 GOPATH

A 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.5

5. Set an admin API key when you need admin endpoints:

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

6. Query organization usage with an admin key:

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

7. Read command-specific help:

openai --help

openai responses create --help

8. Pass a file as an argument:

openai <command> --arg @abe.jpg

9. Pass a file inside JSON:

openai <command> --arg '{image: "@abe.jpg"}'

10. Pass a file inside YAML:

openai <command> <<YAML
arg:
 image: "@abe.jpg"
YAML

11. Escape an @ string:

openai <command> --username '\@abe'

12. Use explicit file encoding:

openai <command> --arg @file://myfile.txt

The @data:// syntax sends a file as base64-encoded data.

openai <command> --arg @data://file.txt

13. Run the project locally after cloning the repository:

./scripts/run args...

Quick 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@version

A local SDK copy can also serve as the linked target.

./scripts/link ../path/to/openai-go

The script defaults to ../openai-go when no argument is supplied.

./scripts/link

Alternatives 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 CLI GitHub Repository: View the source code, installation notes, and project license.
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 OpenAI CLI with other terminal-based AI coding agents.
Free AI Tools for Developers: Browse developer-focused AI tools for code work, debug tasks, documentation, and app building.

Pros

Open-source under OpenAI.
Installs via Homebrew or Go.
Seven output formats.
GJSON output transforms.
Explicit file encoding syntax.
Standard and admin API keys.

Cons

No graphical interface.
Not a coding agent.
Requires terminal comfort.
Admin endpoints need admin keys.
Debug logs can expose data.

FAQs

Q: Is the OpenAI CLI free?
A: The CLI is free and open-source. API usage is billed through your OpenAI account based on the endpoints and models you use.

Q: Does the OpenAI CLI require a signup?
A: You need an OpenAI account and a valid API key for standard API calls. You need an admin API key for organization-level admin endpoints.

Q: What is the difference between the OpenAI CLI and the OpenAI Codex CLI?
A: The OpenAI CLI is an API wrapper for terminal requests, resource management, and usage stats. The Codex CLI is an agentic coding tool that reads and edits files on your local machine in response to natural language prompts.

Q: Does the OpenAI CLI run on Windows?
A: The Go-based install works on Windows, macOS, Linux, and other platforms Go supports. The Homebrew method is mainly for macOS and Linux environments.

Q: Can the OpenAI CLI send local files to the API?
A: Yes. You can pass files with @filename, send plain text with @file://, or send base64-encoded data with @data://.

Q: Should you use debug mode?
A: Debug mode is useful for troubleshooting HTTP requests, but it can show request bodies, response bodies, and sensitive data. You should keep debug logs private and remove secrets before sharing logs.