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
- Codex CLI: approval and sandbox modes (and what --yolo does)
- Configure Codex with config.toml
- Codex AGENTS.md: global, project and override instruction files explained
- Codex MCP servers: codex mcp add and [mcp_servers] in config.toml
- Codex sandbox modes: read-only, workspace-write, danger-full-access and network access
- Codex skills: create SKILL.md, skill folder locations and $skill invocation
- Codex hooks: hooks.json, PreToolUse allow/deny, exit code 2 and config.toml [hooks]
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 →