OpenAI now has an official command line for its API. The repository openai/openai-cli describes itself as "the official CLI for the OpenAI REST API," is written in Go, is licensed Apache-2.0, and had about 777 stars and 559 commits when we looked on October 22, 2026. It surfaced on Hacker News the same morning, where the thread had a few dozen points and a small discussion.
This guide covers what the tool does, how to install and authenticate, the commands most developers will use first, and the details in the README that matter for security and scripting. It is a reference built from the README and docs, not a claim that we benchmarked every endpoint. For comparison with other vendor CLIs, see our references for Claude Code commands and Gemini CLI slash commands.
TL;DR: OpenAI CLI at a glance
| Question | Answer |
|---|---|
| What is it? | A Go command line wrapping the OpenAI REST API, including admin endpoints |
| License | Apache-2.0 |
| Install | brew install openai/tools/openai, or go install (Go 1.26 or later) |
| Auth | OPENAI_API_KEY; OPENAI_ADMIN_KEY for admin endpoints |
| Command shape | openai resource subresource command flags |
| Output | Readable text by default, even in pipes; json, jsonl, yaml, raw via --format |
| Updates | Notice only, once a week at most; disable with OPENAI_CLI_NO_UPDATE_CHECK=1 |
| Contributions | Pull requests limited to repository collaborators; issues welcome |
How to install and authenticate
On macOS or Linux with Homebrew:
brew install openai/tools/openai
With Go 1.26 or later:
go install 'github.com/openai/openai-cli/cmd/openai@latest'
The binary lands in your Go bin directory, by default the home directory's go/bin folder, so add it to your PATH if the command is not found. Then set a key:
export OPENAI_API_KEY="sk-..."
openai help setup
The help setup page explains how to enter the key safely, which matters because keys typed into a shell can end up in history. For admin endpoints you need a separate admin key in OPENAI_ADMIN_KEY. Other environment variables the README lists are OPENAI_ORG_ID, OPENAI_PROJECT_ID, OPENAI_WEBHOOK_SECRET, OPENAI_CUSTOM_HEADERS and the two mutual TLS file variables.
The commands you will use first
The structure is resource-based. A first call to the Responses API looks like this, straight from the README:
openai responses create --input "Say this is a test" --model gpt-5.5
Admin reporting uses the admin key:
openai admin organization usage completions --start-time 1735689600 --end-time 1735776000 --bucket-width 1d
Browse everything with openai, openai --help, or openai admin --help. Help works without an API key or network connection, and openai help COMMAND shows the same page as --help.
Files
Upload with an explicit purpose, inspect metadata, then download:
openai files upload "upload space.txt" --purpose user_data
openai files get file-example
openai files download file-example --output "downloaded copy.txt"
Upload takes a plain path with no added at-sign, which avoids the accidental-file-read behavior described below.
Images
openai images generate --prompt "A tiny orange robot" saves results to a gpt-images folder inside Downloads and prints their paths, even in pipes. According to the README, when you do not set a model the CLI uses gpt-image-2.5-sunburst; --model picks another ID, --name sets a filename, and --output-dir chooses an existing directory. Existing files are kept. images edit also saves new results while preserving sources, and images create-variation is retired, so use images edit with a GPT Image model and a prompt instead. openai images preview redisplays a saved image without an API request.
The first eligible interactive run quietly saves image-picker Tab shortcuts for future Bash, zsh and fish sessions, with an opt-out described in the docs. That is worth knowing if you dislike tools editing shell setup.
Output, errors and scripting
By default, successful JSON responses print as readable text, including in pipes. Scripts that parse API data should pass --format json or --format jsonl. The --transform flag extracts data with GJSON syntax. Errors print actionable summaries to stderr; --format-error json returns the original API error details, and --transform-error extracts fields such as the error code. Summaries omit rejected values and request URLs, though the README warns that explicit API error details can contain server-supplied sensitive data.
Two practical consequences. First, any script written assuming raw JSON by default needs --format json. Second, treat debug output carefully: --debug logs HTTP requests and bodies, and the README tells you not to share those logs if they may contain sensitive payloads.
Security features worth knowing
The README spends real space on security, which is unusual for a CLI and relevant for teams that run it in CI.
- Untrusted stdin mode. The CLI can read local files from at-sign references inside JSON or YAML, such as an image path in a request body. If you pipe in data from an untrusted source, set
OPENAI_UNTRUSTED_STDIN=1so those references are treated as literal text and cannot read local files. File-upload parameters then have to be passed as explicit flags. - Custom headers from the environment. Use
OPENAI_CUSTOM_HEADERSfor credential-bearing headers so secrets stay out of command arguments and shell history. Supplied header values are hidden in help and redacted in debug logs. - Mutual TLS (beta). To authenticate with a client certificate, provide the certificate and private key as separate PEM files through OPENAI_MTLS_CLIENT_CERT_FILE and OPENAI_MTLS_CLIENT_KEY_FILE, and set the base URL to the mTLS endpoint yourself, since the CLI does not select it automatically. HTTPS proxies are rejected to avoid presenting the client certificate during the proxy handshake. You must opt in to OpenAI's Mutual TLS Beta Program first.
- HTTPS enforcement. A custom
--base-urlmust use HTTPS except for localhost or loopback addresses.
If you run agents that call this tool, keep the same discipline as for other secrets: our guide to the OpenAI secure MCP tunnel covers one way to keep internal systems off the public internet, and the LiteLLM compromise post shows what happens when API keys leak from tooling.
What developers on Hacker News said
The discussion is small but touches the right questions. One commenter, hahahacorn, guessed the strategy is to train models to use first-party tools efficiently so they default to services such as managed agents, and was surprised it had not shipped sooner. Another, mi_lk, asked when to use it over Codex and whether other tools or agents are meant to call it. A third, throw20261022, warned about building deeply on OpenAI tooling, claiming OpenAI deprecates many products within two years. These are individual opinions, not verified facts, and the repository's own history is the better evidence of maintenance: 559 commits and a changelog in the repo.
On the Codex question, the README does not describe the CLI as an agent. It is a thin wrapper for calling API endpoints, so the honest answer is that they do different jobs. Our Codex usage and sign-in post covers the agent side.
Practical uses for a team
A command line over the whole API earns its place in a few repeatable situations, even if you already use an SDK.
Cost and usage checks. The admin usage commands take a start time, end time and bucket width, so a scheduled job can pull yesterday's completions usage into a spreadsheet or alert without writing client code. Because admin endpoints need a separate admin key, keep that key out of developer laptops and limit it to the job that needs it.
Debugging production calls. When an application gets a surprising answer, reproducing the exact request from a terminal removes your application code from the equation. The --debug flag shows the HTTP exchange, and --format-error json returns the raw error envelope, which helps when a vendor error message is vague.
One-off file and image work. Uploading a file for later use, or generating a quick image with the default preset, is faster than opening a notebook. The behavior of saving results to a predictable folder and keeping existing files makes it safe to run repeatedly.
CI smoke tests. The tool skips update checks in CI and when streams are redirected, so it will not add surprise network calls to pipelines. A short models list check can confirm that a key and project are valid before a deploy.
What people are asking
Is this the same as the old Python command that shipped with the SDK? The README does not say, so do not assume compatibility. This tool is a separate Go project with its own command structure.
Will it work with other providers? It targets the OpenAI REST API, though a custom --base-url is supported, subject to the HTTPS rule. Compatibility with third-party servers is not documented.
Can an AI agent drive it? Nothing prevents that, and the untrusted-stdin protection suggests the authors expect piped data from other programs. Give agents a restricted key, because a CLI that can read files and call admin endpoints is powerful in the wrong hands.
Where it fits against other tools
| Need | Better fit |
|---|---|
| Call one endpoint from a shell script or cron job | OpenAI CLI |
| Debug a request or inspect usage and costs | OpenAI CLI, including admin usage reports |
| Embed model calls in an app | An official SDK |
| Autonomous coding in a repo | Codex or another coding agent; see our Claudex setup guide |
| Route across providers | A gateway such as Prime Inference |
Limits and open questions
The repository forbids pull requests from non-collaborators, so outside contributors can file issues only. The generated-code layout (a generated folder, a release-please setup and a Stainless-style stats file) suggests much of the surface is produced from the API spec, which keeps it current but also means the command list will track API changes closely. We have not tested every command against live endpoints, and model IDs in examples, such as gpt-5.5 and the default image model, may differ from what your account can access. Check your own model list with openai models list.
Related reading
- Claude Code commands: complete reference
- Gemini CLI slash commands reference
- Codex usage limits and sign-in with ChatGPT
- OpenAI secure MCP tunnel guide
- Prime Inference launch
- LiteLLM 1.107.0 compromise: what to do
- What is MCP? Complete guide
- Google's Gemini API CLI, the Gemini counterpart for shell agents
Details are from the openai/openai-cli README on October 22, 2026 and may change with new releases. See OpenAI's API documentation for current endpoints.