Readable text by default, literal headers, and one retired subcommand in openai-cli
Official CLI for the OpenAI API
At a glance
- What is it?
- The official CLI for the OpenAI REST API, written in Go. Resource-shaped commands, readable output even inside a pipe, literal header values, one retired image subcommand, and a release automation marker that brackets its own install section.
- Who is it for?
- openai-cli suits someone who wants the REST endpoints as commands and nothing more, and it suits a pipeline only after every call carries `--format json` or `--format jsonl`, because `auto` stays readable inside a pipe.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- openai/openai-cli1,168 ★ · +470
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| openai/openai-cli | 698 | 1.2k |
470 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Every row in the environment table says Required: no
The environment table has nine rows and every one of them reads Required: no, with a default value of null. No variable is mandatory before the CLI starts, which pushes the pairing between variables and flags onto the reader: `--api-key` reads `OPENAI_API_KEY`, `--admin-api-key` reads `OPENAI_ADMIN_KEY`, `--organization` reads `OPENAI_ORG_ID`, `--project` reads `OPENAI_PROJECT_ID`, `--webhook-secret` reads `OPENAI_WEBHOOK_SECRET`, and a mutual TLS pair arrives through `OPENAI_MTLS_CLIENT_CERT_FILE` and `OPENAI_MTLS_CLIENT_KEY_FILE`. Standard endpoints and admin endpoints want different keys, and the two examples keep them apart:
export OPENAI_API_KEY="sk-..."
export OPENAI_ADMIN_KEY="sk-admin-..."Two rows have no flag of their own. `OPENAI_CUSTOM_HEADERS` sits in the table with a null default and is never named in the global flag list, so the format it expects appears nowhere in the README. `OPENAI_UNTRUSTED_STDIN` is the other one, and its default is `false` rather than null, which makes it the single variable whose off state is spelled out.
auto prints readable text even when stdout is a pipe
`--format` takes `auto`, `text`, `explore`, `json`, `jsonl`, `pretty`, `raw` and `yaml`, and `auto` resolves to readable text unless the command is extracting data. Successful JSON responses print readable text by default, and that default holds inside a pipe, so a shell script capturing stdout gets prose unless it asks for something else. `--format json` or `--format jsonl` is what a parser needs, and `openai images generate` prints its saved file paths even when the output is piped.
Help is the part that costs nothing. Running `openai` alone prints a short starting guide, and help works without an API key or network connection:
openai help setup # Enter your API key safely
openai images generate --help # Example and common inputs
openai help --all images generate # Every image option and its details
openai help --all # Command groups and global optionsAdding `--help` or `-h` to any command changes only what is displayed: behavior, defaults and output formats stay as they are. Extraction, binary output and how far readable presentation reaches are pushed into docs/readable-output.md rather than the main page.
Header values are literal, and an empty value is still a value
`--header`, shortened to `-H`, adds a request header written as `Name: Value`, and it may sit on either side of the resource command:
openai --header 'X-Trace-ID: example-123' models list \
-H 'X-Client-Label: local,manual'Nothing in the value is interpreted. Commas and colons survive, an `@` prefix does not read a file, and surrounding spaces and tabs are trimmed off. `-H 'X-Example:'` sends an empty value, which is not the same as sending no header. When a name repeats, the last value wins regardless of case, and it overrides both the default headers and the endpoint-specific ones.
That is where the request headers section stops. Its final sentence ends mid-word, after `overriding default and endpoint-specific hea`, so how a repeated name interacts with a header the endpoint already sets is left unsaid. For a tool where a header can carry a trace id or an auth override, case-insensitive last-wins is the only part of the conflict behavior that got written down.
images create-variation is retired, and existing files are kept
Three defaults decide where an image lands. The output directory is `~/Downloads/gpt-images/`, the model is `gpt-image-2.5-sunburst` when no explicit model or legacy response format is given, and files already on disk are kept rather than replaced:
openai images generate --prompt "A tiny orange robot"`--model` takes an exact ID, `--name` sets the filename, and `--output-dir` points at a directory that already exists. The saving is tied to the default format as well: `--format json` returns the API data without saving anything and without applying the CLI preset, so a caller that switches format to get parseable output also gives up the file unless it asks for the save separately. `images edit` saves its new results and keeps the source files.
One command is gone rather than deprecated. `images create-variation` is retired and no longer available, and the stated replacement is `images edit` with a GPT Image model and a prompt. docs/image-generation-saving.md holds the commands and defaults for this area.
images preview makes no request, and inline is remembered between runs
Preview is the one images path that spends nothing. `openai images preview "path/to/image.png"` redisplays an image already saved on disk without making an API request, so rechecking an earlier run needs no key configured and no network round trip. Whether new images appear automatically is remembered between runs through `openai images inline on` or `off`, and a per-command `--inline auto`, `on` or `off` overrides that stored setting for a single call. The `on` setting also permits an image font in local Apple Terminal, which is the only platform note in this corner of the README.
Read together with the previous section, the image corner splits cleanly. Saving costs an API call and defaults to a fixed directory, a fixed model and no overwrite protection beyond keeping what exists. Preview and inline display cost nothing and remember your last choice.
Error summaries drop the rejected values and the request URLs
Errors print readable summaries to stderr, and those summaries are lossy on purpose: they omit rejected values and request URLs. `--format-error json` restores the original API error details, including unknown fields and stream error events reported by the SDK. Extraction paths for those events include the `error` envelope, so `--transform-error error.code` pulls a code out of a failure independently of anything the success path produced.
The two format systems overlap in a way worth memorizing. Explicit `--format` values of `json`, `jsonl`, `raw` and `yaml` apply to errors too unless `--format-error` overrides them, and an explicit `--format-error auto` or `text` puts the summaries back. Malformed or empty error bodies receive a safe diagnostic instead of a parse failure, and the HTTP status shows up only when the SDK retained it.
The trade is stated plainly: summaries drop the values and URLs that explain a rejection, while explicit API error details can carry server-supplied sensitive data. Redirecting `--format-error json` into a log is a decision about what that log now holds.
--debug logs request and response bodies
`--debug` is the flag to think about before running this on a shared machine. It enables debug logging that includes HTTP request and response details and bodies, and the README's own note is not to share those logs if they may contain sensitive payloads. Request bodies are the inputs you typed, response bodies are the model output, and neither is redacted on the way into the log.
`--base-url` is the other half of that decision. It points the CLI at a custom API backend URL, and `--api-key` sends the key to whichever host that resolves to. The README does not discuss the pairing, so an alias such as `alias openai='openai --base-url ...'` in a shell profile deserves a manual check. `--transform` and `--transform-error` apply GJSON syntax to data output and error output separately, which is the other place where a filter expression can hide a field that would otherwise be visible in the pipe.
The release-please markers wrap the install section, not a version line
Installation has two branches. `brew install openai/tools/openai` comes from a tap, while `go install 'github.com/openai/openai-cli/cmd/openai@latest'` needs Go 1.26 or later, matching the `go 1.26.0` line in go.mod and the `.go-version` file at the top level. The Go route drops the binary in `$HOME/go/bin`, or `$GOPATH/bin` when GOPATH is set, which is the step behind commands not being found until PATH is fixed:
export PATH="$PATH:$(go env GOPATH)/bin"The release automation is wired into the README itself. The comment marker `<!-- x-release-please-start-version -->` opens above the Installation heading and `<!-- x-release-please-end -->` closes below the Go bin note, with no version string between them. `.release-please-manifest.json` and `release-please-config.json` sit at the top level next to `.goreleaser.yml`, `.goreleaser-version` and `.goreleaser-checksums`, alongside `api_reference/`, `cmd/`, `internal/`, `pkg/`, `scripts/`, `AGENTS.md`, `SECURITY.md` and `.castiron-ratchet.json`. go.mod pins `github.com/openai/openai-go/v3 v3.68.0` and builds terminal output on charm.land Bubbletea v2.0.8 and lipgloss v2.0.5. v1.32.0 shipped on 2026-10-02, one day after v1.31.1 and v1.31.0.
Editorial conclusion
openai-cli suits someone who wants the REST endpoints as commands and nothing more, and it suits a pipeline only after every call carries `--format json` or `--format jsonl`, because `auto` stays readable inside a pipe. Before running it on a shared machine, check three things by hand: whether `OPENAI_CUSTOM_HEADERS` is set in the environment, since the global flag list never gives its format; whether `--base-url` is aliased to an internal gateway somewhere in a shell profile, since `--api-key` follows it there; and whether debug logs from `--debug` are being kept, because those files carry full request and response bodies. v1.32.0 shipped on 2026-10-02, one day after v1.31.0 and v1.31.1, so expect flags and defaults to move between releases.
Frequently asked questions
how to install openai cli
Two documented paths: `brew install openai/tools/openai` from a tap, or `go install 'github.com/openai/openai-cli/cmd/openai@latest'` with Go 1.26 or later, which places the binary in `$HOME/go/bin` or `$GOPATH/bin` when GOPATH is set.
what is openai cli
The official command line for the OpenAI REST API, written in Go and released under Apache-2.0. It uses a resource-based structure, `openai <resource> [subresource...] <command> [flags...]`, with standard endpoints reading `OPENAI_API_KEY` and admin endpoints reading `OPENAI_ADMIN_KEY`.
Does openai-cli need an API key before it will print help?
No. Running `openai` with no arguments prints a short starting guide, and the README states that help works without an API key or network connection. `openai help --all` lists command groups and global options.
Where does openai-cli put generated images, and does it overwrite existing files?
`openai images generate --prompt "A tiny orange robot"` saves to `~/Downloads/gpt-images/` and prints the paths. Without an explicit model or legacy response format it uses `gpt-image-2.5-sunburst`, and existing files are kept.
What does openai-cli's debug logging capture?
`--debug` enables debug logging that includes HTTP request and response details and bodies. The README warns against sharing those logs when they may contain sensitive payloads.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 3 in the last 30 days; newest first.
- OpenAI CLIHacker News · Oct 22, 2026 · 243 points · 111 comments
- State of AI Instruction Quality: Coding Agent Comparisondev.to · Oct 21, 2026 · 6 points · 0 comments
- OpenAI CLI – Official CLI for the OpenAI APIHacker News · Oct 21, 2026 · 2 points · 0 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/openai-openai-cli)Star history chart for your README
[](https://hysenlabs.com/projects/openai-openai-cli)Was this useful?