Skip to content
AgentAtlas

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

How do I run Codex non-interactively with codex exec?

Run codex exec "your task" to run Codex once without the interactive TUI. It runs in a read-only sandbox by default, so add --sandbox workspace-write if it needs to edit files. Use --json for a JSON Lines event stream, -o to save the final message, and --output-schema to force a structured answer.

Compare: headless mode for scripts and CI in every AI coding agent →

Basic usage

One-off task

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

Save output with tee

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

Read the prompt from stdin

cat prompt.txt | codex exec -

By default codex exec must run inside a Git repository. Add --skip-git-repo-check to run elsewhere.

Let it edit files

By default, codex exec runs in a read-only sandbox. Use --sandbox workspace-write to allow edits. Use danger-full-access only in a controlled environment. The old --full-auto flag is no longer supported.

Allow edits in the workspace

codex exec --sandbox workspace-write "fix the failing unit tests"

Get machine-readable output

  • --json: stdout becomes a JSON Lines stream of every event, such as thread.started, turn.started, turn.completed, turn.failed, item.* and error.
  • --output-last-message <path> or -o <path>: write only the final message to a file. It still prints to stdout.
  • --output-schema <file>: ask for a final answer that matches a JSON Schema.

Stream events to jq

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

Structured output to a file

codex exec --output-schema ./schema.json -o ./project-metadata.json "extract the project metadata"

Resume runs and skip saved state

Continue the last run

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

Continue a specific run

codex exec resume <SESSION_ID>
  • --ephemeral: do not save session rollout files to disk.
  • --ignore-user-config: skip loading $CODEX_HOME/config.toml.
  • --ignore-rules: skip user and project execpolicy .rules files.

Authentication in CI

codex exec reuses your saved CLI login by default. To use a different API key for one run, set CODEX_API_KEY inline.

Use an API key for one run

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

Do not set OPENAI_API_KEY or CODEX_API_KEY as a job-level environment variable in workflows that run code from the repository. For GitHub Actions, OpenAI recommends the openai/codex-action action instead of installing the CLI and passing the key to a shell step.

Sources

More Codex guides

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →