Scripting the OpenAI API: When the New openai CLI Beats curl

The practical answer up front: if your shell scripts generate images, upload files, or submit and wait on batches against the OpenAI API, the official openai CLI is worth adopting over raw curl, but only after you harden it for CI. According to OpenAI’s own README, generated images default to ~/Downloads/gpt-images/ unless you pass --output-dir, go install requires Go 1.26+, and a failed request can leave an incomplete output file behind redirected results. None of that is a reason to stay on curl; all of it is a reason to route deliberately.

One evidence caveat belongs here rather than in a footnote: every behavioral claim about the openai CLI in this article comes from a single vendor README, fetched 2026-10-22. Nothing cited here benchmarks the CLI against curl or the SDKs, and the contrast with Codex CLI’s update behavior rests on one user-filed GitHub issue. Treat what follows as a routing rule built from documented affordances, not a measured comparison.

Two terminal binaries, one vendor

OpenAI now splits its terminal surface in two, and says so explicitly. From the openai-cli README: “Use openai when you want to call a specific API or put API operations in a script. Use Codex CLI (codex) when you want a coding agent to work on a project: read and edit code, run commands, and help implement or debug a change.”

The CLI’s stated purpose matches that division: “Call the OpenAI REST API from your terminal or shell scripts. Generate images, upload files, submit batches, and inspect API results without writing an application.” From the Codex side, OpenAI’s Codex CLI documentation sanctions codex exec as the non-interactive entry point: “Compose with scripts and CI Use Codex interactively or call codex exec from repeatable workflows and pipelines.”

So the first routing decision is not openai versus curl. It is openai versus codex: scripted API operations belong to the former, agentic coding runs to the latter. Sending a pipeline job to the wrong binary matters more than usual because, as a later section covers, the two tools have opposite update models, and your audit policy has to treat them separately.

A task-routing checklist

Here is the routing rule this article argues for, with the evidence status of each row:

The last two rows before codex exec are inference, not documentation. The README does not enumerate which endpoints the CLI covers and which it does not, and nothing fetched measures how it behaves under rate limits or partial failures. curl plus jq remains the fallback precisely because it imposes no coverage boundary: if the API accepts the request, curl can send it.

The install decision is really a toolchain decision

The README documents three install paths: prebuilt binaries from GitHub Releases for macOS, Linux, and Windows; Homebrew via brew install openai/tools/openai; and go install github.com/openai/openai-cli/cmd/openai@latest, which carries a prerequisite curl never imposed: “Requires Go 1.26 or later.” The go install path also drops the binary into $HOME/go/bin (or $GOPATH/bin if GOPATH is set), so the binary lands wherever the Go toolchain says, not where your package manager tracks.

For a laptop, any of the three works. For a fleet, the choice is a policy statement. If Go 1.26+ is already standard on your runners, go install fits existing toolchain management. If it is not, you are deciding whether to adopt a compiler toolchain to install one API client. My recommendation: unless Go is already fleet standard, install from GitHub Releases or Homebrew and pin the version. The two paths are not equivalent for auditing. Homebrew keeps the binary inside the package manager that installed it; a pinned GitHub Releases download fixes the version but still requires your own artifact inventory and checksum step.

There is an independent reason to expect friction here. An empirical study of 3,864 issues across Claude Code, Codex, and Gemini CLI found API and integration errors the top root-cause category at 21.4%, with configuration and setup second at 15.9%, and named incompatible runtime versions as a failure mode. A CLI whose go install path requires Go 1.26+ sits squarely in the two categories that study found most bug-prone. That is not a finding about this CLI specifically; it is a prior about where this class of CLI tooling tends to hurt first.

Two keys, not one

Scripts authenticate with OPENAI_API_KEY, read from the environment or a secret manager. Admin endpoints are different: per the README, “Admin endpoints use OPENAI_ADMIN_KEY, a separate admin API key.”

This split is easy to get right and worth getting right. A batch-submission cron job needs the standard key and nothing else; an organization-usage export needs the admin key and nothing else. Keep them in separate secrets with separate scopes, and a leaked CI variable for the nightly batch job does not carry administrative reach. curl scripts can enforce the same discipline by hand, but the CLI makes the boundary structural rather than conventional.

Making output safe to pipe

Raw curl gives you whatever the server sent, and your script copes. The CLI inverts that: the default output is readable text even in pipes, which means a script that forgets to ask for structure gets prose. From the README: “Choose —format json for a JSON document or —format jsonl for records. The default output is readable text, even in pipes.” The documented idiom is explicit, for example openai models list --format jsonl | jq '.id', and --transform extracts fields with GJSON syntax when you do not want to shell out to jq at all.

Errors go to stderr as readable summaries, with --format-error json available when the script needs the API’s error details rather than a human sentence.

The sharper rule is about exit status. The README itself warns: “Check the command’s exit status before using redirected results; a failed request can leave an incomplete output file.” Independent research says the same thing from the other direction. A study evaluating LLM-generated CLI tools end to end documented cases where a tool exited 0 while producing no system-level side effects, concluding that “running without crashing” does not equate to task completion. That finding is about a different class of tool, but the operational lesson transfers: check the exit code, then verify the artifact. For an image job, that means the file exists, is non-empty, and parses. Exit 0 plus a zero-byte PNG is a failure your pipeline should catch, not propagate.

One small help for CI smoke checks: per the README, help output needs no API key or network connection, so openai --help works as an offline install-verification step.

CI traps worth writing into the runbook

Three defaults in the README will bite unattended runs if you do not override them.

Images go to your Downloads folder. The README states: “Images are saved to ~/Downloads/gpt-images/, and the command prints their paths. Use —output-dir for an existing destination directory or —name for a filename.” On a headless runner, ~/Downloads may not exist, may not be writable, or may be nowhere near your artifact-collection step. Always pass --output-dir pointing at a directory the job created.

Piped input can trigger local file reads. The CLI supports @path syntax in JSON or YAML input, which means a crafted payload could reference local files. The documented mitigation: “Use OPENAI_UNTRUSTED_STDIN=1 when piping JSON or YAML from an untrusted source so input cannot cause local file reads.” In that mode, upload paths must be explicit flags. If your pipeline ever processes input it did not generate, export this.

Update notices are check-only, but they still run. The README: “The CLI checks for updates on eligible interactive runs; it never installs them automatically. Set OPENAI_CLI_NO_UPDATE_CHECK=1 to disable checks and notices.” Check-only is the right default for a scripting tool, but in CI you want determinism and quiet logs, so export OPENAI_CLI_NO_UPDATE_CHECK=1 and upgrade on your own cadence.

A minor stateful note for managed environments: the README also documents that the first eligible interactive run saves image-picker Tab shortcuts for future shell sessions. Harmless on a laptop, worth knowing about on shared machines where a “read-only” invocation writes shell state.

Opposite update philosophies under one roof

Here is the consequence that elevates this from a tool review to a policy question. The openai CLI never installs updates automatically. Codex CLI, according to issue #48195 filed against version 0.157.0, does something close to the opposite. The reporter describes an interactive session that “Starts a detached updater (codex app-server daemon pid-update-loop) that checks for updates 5 minutes after start and then hourly, downloads new releases and restarts the backend,” and that the daemon, per the same issue, “Copies the whole platform package (~374 MB: codex, codex-code-mode-host, bundled bwrap/zsh/rg) into ~/.codex/packages/app-server-daemon/releases/<version>/ — byte-identical to what npm had just installed — and runs the daemon from that copy.” The same issue says the daemon “keeps running after every Codex window is closed (reparented to PID 1) until codex app-server daemon stop or a reboot,” and notes that updater restarts can kill active turns, referencing related issue #40969.

Two caveats before you write policy from this. First, this is one user-filed issue against one version, medium-confidence evidence, not confirmed OpenAI design intent, and the daemon behavior could change or already have changed by the time you read this. Second, even taken at face value, it describes interactive-session behavior; codex exec in pipelines is a separate question the issue does not settle.

But the policy implication holds regardless of how the Codex situation resolves: you cannot write one update rule for “OpenAI CLI tools.” One binary checks and waits for you; the other, per this report, checks for updates hourly, then downloads new releases and restarts the backend, with a version decoupled from whatever your package manager installed. Fleet install and audit policy needs a per-binary entry: which install path, which version pin, whether a background process is expected to exist afterward, and who owns stopping it.

What the evidence cannot settle

The honest limit of this article is that its primary source is a README. Research categorizing GitHub README content found that “How” material, installation, requirements, dependencies, is the most common category of README documentation. That is exactly where the Go 1.26+ note and the install instructions sit. READMEs are good at telling you what a tool is supposed to do; they are not evidence of what it does under load, at rate limits, across versions, or against a partially failed API.

So before a fleet rollout, verify what this article could not:

• Coverage. Which endpoints does the CLI actually wrap? Anything missing stays on curl + jq.
• Exit behavior under failure. Does a rate-limited or server-error response exit non-zero in practice, and does --format-error json emit parseable output in every failure mode your retry logic cares about?
• Artifact correctness. Does batches wait --output-dir produce complete results files, and what does a partial download look like?
• The Codex daemon. Reproduce or refute issue #48195 on your own install of the current version before writing audit policy around it.
• The version-specific defaults. The ~/Downloads/gpt-images/ default, the flags, and the Go prerequisite are all one release away from changing. Re-check the README on upgrade.

The routing rule

Route scripted OpenAI API operations (image generation, file upload and download, batch submit-and-wait, model and file exports, admin usage) to the openai CLI, hardened for CI: install from GitHub Releases or Homebrew unless Go 1.26+ is already fleet standard, always pass --output-dir, request --format json or jsonl, check exit codes and then verify the artifacts, keep OPENAI_API_KEY and OPENAI_ADMIN_KEY in separate secrets, and export OPENAI_CLI_NO_UPDATE_CHECK=1 plus OPENAI_UNTRUSTED_STDIN=1 wherever input is untrusted. Keep curl + jq for endpoints the CLI does not cover, keep the SDKs for anything that needs real error handling, and keep agentic runs on codex exec. Write the update policy per binary, because one binary is documented as check-only while a filed report describes the other as self-updating.

Where does that leave “beats curl”? For the workloads the CLI covers, it beats curl on exactly the things shell scripts are worst at: structured output you do not have to scrape, a batch workflow with a built-in wait, local file management, and an auth boundary that is structural rather than remembered. For everything else, curl’s lack of opinions is the feature. I would trial the CLI on jobs that can tolerate a restart and a re-run, prove out the exit-code and artifact checks above, and only then let it near the cron jobs whose failure means rebuilding something by hand. The README makes a good case for the tool; your runners still have to confirm it.

Frequently Asked Questions

Where does the openai CLI save generated images by default?

Images are saved to ~/Downloads/gpt-images/, and the command prints their paths. Use —output-dir for an existing destination directory or —name for a filename.

How do I prevent the openai CLI from checking for updates in CI?

The CLI checks for updates on eligible interactive runs; it never installs them automatically. Set OPENAI_CLI_NO_UPDATE_CHECK=1 to disable checks and notices.

What Go version is required to install the openai CLI via go install?

Requires Go 1.26 or later.