codex exec: run Codex non-interactively in scripts and CI

codex exec runs Codex without the interactive terminal UI. You pass a prompt, Codex works through the task with the sandbox and approval settings you set up front, streams progress to stderr, and prints only the final answer to stdout. That makes it the tool for CI jobs, scheduled scripts and shell pipelines.

This guide covers flags, JSON and schema output, resuming runs, safety defaults and CI patterns, based on OpenAI's non-interactive mode docs and command reference, read on 24 October 2026. For installing and signing in, see the Codex CLI guide.

What is codex exec and when should you use it?

OpenAI's docs list four reasons to reach for it: running Codex in a pipeline (CI, pre-merge checks, scheduled jobs), producing output you can pipe into other tools, chaining command output into Codex, and running "with explicit, pre-set sandbox and approval settings."

Use the interactive codex command when you want to steer a task as it runs. Use codex exec when nobody will be watching.

How do you run codex exec?

Pass the task as a single argument:

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

# save just the final answer
codex exec "generate release notes for the last 10 commits" | tee release-notes.md

You can feed it input two ways:

• Prompt plus stdin. If you pipe data in and also give a prompt, the prompt is the instruction and the piped content is extra context.
• Stdin as the whole prompt. Omit the prompt, or pass -, and Codex reads the prompt from stdin.

# piped data as context
npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix"

# a prompt stored in a file
cat prompt.txt | codex exec -

Codex expects to run inside a Git repository, a guard against destructive changes. Use --skip-git-repo-check only when you are sure the folder is safe to modify.

Which codex exec flags matter most?

These come from the official codex exec reference:

How do you get JSON output?

Add --json and stdout becomes a JSON Lines stream, one event per state change:

codex exec --json "summarize the repo structure" | jq

Event types include thread.started, turn.started, turn.completed, turn.failed, item.* and error. Items cover agent messages, reasoning, command executions, file changes, MCP tool calls, web searches and plan updates. The turn.completed event carries token usage, which is handy for cost tracking in CI.

If you only need the final answer, -o path writes it to a file and still prints it to stdout.

How do you get structured output with --output-schema?

When a later step needs stable fields, give Codex a JSON Schema:

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

The final response then matches that shape, so a script can read it with jq or any JSON parser. Good uses include risk reports, job summaries and release metadata.

How do you resume or fork a run?

Two-stage pipelines can pick up where the last run stopped:

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

--last picks the most recent session from the current folder, and --all widens the search to every directory. You can also target one session with codex exec resume SESSION_ID.

To try a different approach without touching the original, codex exec fork SESSION_ID "prompt" copies a saved session into a new one; a prompt is required when the fork uses images, --output-schema, --output-last-message or --ephemeral. Add --worktree to a new or forked run to work in a managed Git worktree; it cannot be combined with resume, --ephemeral or --ignore-user-config.

What are the safety defaults?

The headline: "By default, codex exec runs in a read-only sandbox." Codex can read and analyze, but it cannot change files until you allow it.

• Allow edits: codex exec --sandbox workspace-write "<task>".
• Broader access: --sandbox danger-full-access, which OpenAI says to use "only in a controlled environment (for example, an isolated CI runner or container)."
• No more --full-auto: the flag is no longer supported. Switch scripts to --sandbox workspace-write, or to --approve-for-me for automatic approval review.
• Reproducible runs: --ignore-user-config and --ignore-rules keep a developer's local settings out of a controlled automation environment.
• Fail loudly on missing tools: if an MCP server marked required = true fails to start, codex exec exits with an error instead of carrying on without it.

The Codex sandbox guide explains each sandbox mode and how network access works inside them.

How do you use codex exec in CI?

codex exec reuses your saved CLI login by default, but CI usually passes credentials explicitly. For one run with a specific API key:

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

OpenAI's guidance is strict about where that key lives. Do not set OPENAI_API_KEY or CODEX_API_KEY as a job-level environment variable in workflows that check out or run repository code, because build scripts, tests or dependency hooks in the same job can read it.

For GitHub Actions, use the Codex GitHub Action (openai/codex-action@v1) instead. It installs the CLI, starts a Responses API proxy to reduce API key exposure, and runs codex exec with the permissions you choose:

- name: Run Codex
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    prompt-file: .github/codex/prompts/review.md
    sandbox: read-only
    output-file: codex-output.md

Its safety-strategy input defaults to drop-sudo, which removes sudo before Codex runs. Pass extra flags such as --output-schema through codex-args. OpenAI's auto-fix example runs Codex in a job with only contents: read, saves the diff as an artifact, and opens the pull request from a separate job that never sees the API key. The openai/codex-action repository has the full security checklist.

Tips for reliable codex exec scripts

• Start read-only. Give a job write access only when it must change files.
• Prefer schemas over parsing prose. --output-schema beats regex on free text.
• Use profiles for CI. A profile file keeps automation settings apart from your interactive defaults; see the Codex config.toml guide.
• Keep prompts in files. A prompt in .github/codex/prompts/ is reviewed and versioned like code.
• Use --ephemeral on shared runners so session files do not pile up on disk.

Keep your automation prompts in one place

CI prompts are easy to lose across workflows and repos. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, with {{name}} blanks for the parts that change between runs. If a prompt grows into a reusable procedure, the free SKILL.md generator turns it into a skill Codex can load.