codex exec: The Complete Guide to Non-Interactive Codex

codex exec is the switch that turns OpenAI’s Codex from a terminal assistant into a programmable unit of work. One command in, a completed task out, no TUI. OpenAI’s docs describe it for exactly this: “run Codex from scripts (for example, continuous integration (CI) jobs) without opening the interactive TUI.” This guide covers the mechanics, auth on servers, CI patterns, and the operational gap between running it yourself and having it run for you.

The basics

Pass the task as an argument:

codex exec "summarize the repository structure and list the top 5 risky areas"

Codex plans, runs tools inside its sandbox, and writes the final answer to stdout, which makes it composable with anything that reads pipes:

codex exec "extract all TODO comments as a JSON array" | jq '.[] | select(.priority == "high")'

Flags worth knowing from the documented surface:

• Sandbox and approval settings can be preset, so nothing blocks on interactive confirmation.
• Output can be piped and chained into other tools.
• codex exec resume --last continues the previous session with context intact, the building block for multi-stage pipelines.

Auth: plan-backed by default

codex exec reuses the CLI’s saved authentication. Sign in once, and every subsequent exec call runs on that session. OpenAI recommends ChatGPT sign-in so usage is included in your Plus, Pro, Business, Edu, or Enterprise plan; an API key is the metered alternative.

On a headless machine, use the device-code flow:

codex login --device-auth
# CLI prints a code; approve it at chatgpt.com from any browser

This is documented behavior for servers, not a trick. It is also the exact flow you use to connect Codex Hosted: the sign-in happens between you and OpenAI, and the session lands in a container only your account uses.

Using it in CI and scripts

The pattern that works: treat each codex exec call as a job with a clear contract.

#!/usr/bin/env bash
set -euo pipefail

review=$(codex exec "review the diff in HEAD~1..HEAD for bugs; output markdown")
echo "$review" >> "$GITHUB_STEP_SUMMARY"

For PR automation specifically, OpenAI ships an official GitHub Action, documented with API-key auth via repository secrets. That is the right call for shared CI: a repo secret is auditable and revocable, while a personal plan session in a shared pipeline blurs the one-user-one-account line that OpenAI’s terms draw. Plan-backed exec shines where the workload is genuinely yours: your agents, your batch jobs, your automations.

What running it yourself actually involves

The CLI is free; the operations are not. A plan-backed exec box you maintain yourself needs:

• a machine that stays up (your laptop does not),
• session refresh when auth expires, noticed before your cron jobs fail silently,
• a queue, because exec calls are sequential per session and your apps are not,
• usage-limit handling, since plan windows exhaust and reset on their own schedule,
• logs, if you ever want to know what ran and what it would have cost.

That list is the product definition of Codex Hosted. We run the official, unmodified CLI in your private container around the clock, expose it as an OpenAI-compatible endpoint (OPENAI_BASE_URL=https://api.proxyllm.ai/v1), queue and log every request, and fail over to a second account or your API key when a window exhausts. The trade to know about: responses on the Codex lane arrive complete rather than streamed. Details on limit behavior live in what happens when you hit your limit.

Is programmatic use allowed?

Yes, and this one is not a judgment call: non-interactive mode has its own documentation page, an SDK, and a GitHub Action. OpenAI built Codex to be scripted. The fuller policy picture, including the account rules and where OpenAI’s discretion begins, is in is Codex Hosted against OpenAI’s terms?

If you came here from a “why is my OpenAI bill like this” search, the punchline is that exec on a plan replaces metered tokens with a flat subscription. The calculator maps your current bill to a plan tier in thirty seconds.