openai-cli: the official OpenAI API client for your terminal

What openai-cli actually is, and who it is for

The README opens with one line: the project is the official CLI for the OpenAI REST API. That framing matters, because the tool does not add a layer of intelligence on top of the API. It exposes the same endpoints you would otherwise reach with curl or an SDK, wrapped in a command structure of the form openai [resource] <command> [flags...].

The audience follows from that. If you already call the API from shell scripts, Makefiles or CI jobs, this replaces hand-built curl invocations with named subcommands and flag parsing. If you are looking for something that reads your repository, plans edits and runs them, this is not that tool. The repository contains no agent loop in the code paths the README describes, and the README never describes one.

The project is written in Go and released under Apache-2.0. The go.mod file pins the module as github.com/openai/openai-cli and depends on github.com/openai/openai-go/v3, the official Go SDK. The CLI is therefore a client of a client: the SDK handles the HTTP plumbing, and the CLI handles argument parsing, output formatting and environment configuration. Releases are frequent, with v1.15.0 tagged on 2026-09-10, and the last push to the default branch was on 2026-09-17.

Resource-based commands and the environment variables behind them

Every call needs credentials, and the README splits them into two classes. Standard API endpoints read OPENAI_API_KEY. Admin endpoints read OPENAI_ADMIN_KEY, a separate key type obtained from the admin keys page. Both are optional in the environment table, with a default of null, which means the CLI will start without them and fail at request time rather than at startup.

Two more variables scope the request: OPENAI_ORG_ID and OPENAI_PROJECT_ID. Each has a matching global flag, so --organization and --project can override the environment for a single invocation. The same pattern repeats across the rest of the configuration surface: OPENAI_CUSTOM_HEADERS, OPENAI_WEBHOOK_SECRET, OPENAI_MTLS_CLIENT_CERT_FILE and OPENAI_MTLS_CLIENT_KEY_FILE all have flag equivalents.

Output is configurable through --format, which accepts auto, explore, json, jsonl, pretty, raw and yaml. A separate --format-error controls how failures are rendered, and both --transform and --transform-error accept GJSON syntax to pull a single field out of a response. That combination is what makes the tool usable in a pipeline: you can ask for JSON, then select one value, without piping through jq. The dependency list confirms the implementation, with github.com/tidwall/gjson and github.com/tidwall/pretty in go.mod, alongside a set of Charm libraries for the explore and pretty modes.

Installing openai-cli on macOS, Linux and Windows

The README gives two installation routes. Homebrew is the shorter one, and it works on macOS and on Linux systems where Homebrew is available:

brew install openai/tools/openai

After that command completes, openai should be on your PATH and openai --version should print the release you installed. Windows users are not addressed by the Homebrew route; the Go route below works wherever the Go toolchain runs.

The second route builds from source and requires Go 1.25 or later, matching the go directive in go.mod:

go install 'github.com/openai/openai-cli/cmd/openai@latest'

The binary lands in your Go bin directory. The README states the default location is $HOME/go/bin, or $GOPATH/bin when GOPATH is set, and suggests running go env GOPATH to check. If the openai command is not found afterwards, the fix the README gives is to add that directory to your shell profile:

export PATH="$PATH:$(go env GOPATH)/bin"

For a first real call, export a key and hit the responses endpoint. The README uses this exact example:

export OPENAI_API_KEY="sk-..."

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

You should see the API response rendered in the format auto selects. If you want machine-readable output, add --format json. Note that the README does not document a login or credential-storage flow, so the key lives in your environment or in a secret manager that sets it. For repository work, the README also mentions a scripts/run wrapper that executes the tool locally after cloning.

Headers, file arguments and the untrusted-stdin switch

Custom headers go through --header or -H, and the README is unusually precise about their semantics. Values are literal: commas and colons are preserved, and an @ prefix does not read a file. Surrounding spaces and tabs are trimmed. Passing -H 'X-Example:' sends an empty value. When a name repeats, the last value wins regardless of case, and it overrides both default and endpoint-specific headers. Transport-managed headers such as Host and Content-Length keep the transport's behaviour.

The README then draws a line that matters for anyone handling credentials. Header values are hidden in help output and redacted in debug logs, but the recommended path for credential-bearing headers is to have a secret manager set OPENAI_CUSTOM_HEADERS in the CLI's environment rather than passing a literal secret on the command line, where it would land in shell history. That variable takes one Name: Value entry per line. Flags and endpoint-specific header flags override matching environment entries.

File arguments use an @myfile.ext syntax, and the same reference works inside JSON or YAML blobs, either inline as {image: "@abe.jpg"} or through a heredoc. This is where the design gets interesting. Because those references read local files, piping untrusted JSON into the CLI would let a remote producer name any path on disk. The README's answer is OPENAI_UNTRUSTED_STDIN=1, which turns @, @file:// and @data:// references into literal data for bodies, headers and query parameters. File-upload parameters must then be passed explicitly as command arguments. It is a narrow switch with a clear purpose, and the default of false means you have to remember it.

Where openai-cli is the wrong tool, and what to use instead

The clearest limitation is scope. This is an API client, and the README never claims otherwise. If your task is to have a model inspect a codebase, propose a patch and apply it, you need an agent product, not a request wrapper. The search results around this project mix the two constantly, which is a good sign that users arrive with the wrong expectation. The README's own example is a single responses create call with a string input. There is no file-editing loop, no diff review step and no interactive session in the documented surface.

The second limitation is mTLS. The README states mutual TLS is in beta and requires opting in through the OpenAI Mutual TLS Beta Program to activate a CA certificate for your organization or project. Both files must be configured together, and the CLI does not automatically select an mTLS endpoint, so you must set OPENAI_BASE_URL or --base-url yourself. The README's example uses https://mtls.api.openai.com/v1. HTTPS proxies are rejected outright to avoid presenting the client certificate during the proxy's own TLS handshake, while HTTP and SOCKS proxies remain supported. This is a deliberate trade-off: it protects the certificate at the cost of ruling out a common corporate proxy configuration. If your environment terminates TLS at an HTTPS proxy, this tool will not fit without network changes.

The natural alternative is the OpenAI SDK for your language, openai-go in this case. The difference in approach is real: an SDK gives you typed request and response objects and lets you compose calls inside a program, while the CLI gives you a process boundary, shell-friendly flags and output you can transform with GJSON. If your logic already lives in Python or TypeScript, adding a subprocess call to openai-cli buys you very little. If your logic lives in Bash and CI, the SDK is the awkward option and the CLI is the direct one.

Maintenance, releases and the licence

Release cadence is visible in the tags: v1.13.0 and v1.14.0 both landed on 2026-09-09, and v1.15.0 followed on 2026-09-10. The repository is not archived, and the last push to the default branch was on 2026-09-17. The repository layout shows release-please-config.json and .release-please-manifest.json, plus a CHANGELOG.md, which indicates releases are generated from commit messages rather than written by hand. Practically, that means upgrade notes live in the changelog and version bumps track the underlying SDK.

That coupling is the main upgrade cost. go.mod pins github.com/openai/openai-go/v3 at v3.61.0, so a CLI release can move when the SDK moves. If you install through Homebrew, upgrades arrive with brew upgrade. If you install with go install ...@latest, you get whatever the latest tag is at the time you run it, and nothing updates automatically afterwards. Pinning a version in CI means re-running the install step deliberately rather than drifting.

The licence is Apache-2.0, as stated in the repository metadata and present as a LICENSE file at the top level. That is a permissive licence with an explicit patent grant, and it is compatible with commercial use and redistribution. It is not a legal opinion, and if you plan to redistribute a modified binary or embed the code in a product, the NOTICE and attribution requirements in the licence text are worth reading rather than assuming.

Editorial conclusion

Adopt openai-cli if you write scripts or CI jobs that call the OpenAI REST API and want the request body, headers and output format under your control. Do not adopt it if you want an interactive coding agent that edits files; the README describes endpoint calls, not agent behaviour. Before rolling it out, verify two things on your own machine: that the Go bin directory is on your PATH after go install, and that your account has the admin key needed for the admin:organization:usage commands.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. openai/openai-cli on GitHub
4. README
5. Releases