codex exec

What codex exec does

Running codex normally opens an interactive screen. codex exec runs a single task without that screen and exits. The official docs describe it as the non-interactive mode for scripts and CI.

The output behavior matters. Progress streams to stderr, and stdout carries only the final agent message. That makes it easy to redirect or pipe. You pass the task as one quoted argument.

codex exec "summarize the repository structure and list the top 5 risky areas"
codex exec "generate release notes for the last 10 commits" | tee release-notes.md

Permissions: read-only by default

The default sandbox is read-only. It can read and summarize code but cannot edit files. To let it make changes, pass --sandbox workspace-write.

--sandbox danger-full-access allows broad access. The docs say to use it only in controlled environments such as an isolated CI runner or a container. It is not an option to use out of habit on your own laptop.

• --full-auto is no longer supported. Switch to --sandbox workspace-write, or use --approve-for-me, which hands approval requests to automatic review.
• --ignore-user-config skips $CODEX_HOME/config.toml. --ignore-rules skips the user and project execpolicy .rules files.
• If an MCP server you marked required (required = true) fails to start, Codex exits with an error instead of continuing.
• Adding --ephemeral means no session record file is saved to disk.

Making the result machine-readable

With --json, stdout becomes a JSON Lines event stream. You get events such as thread.started, turn.completed, turn.failed, item.*, and error. Items include agent messages, command executions, file changes, web searches, and plan updates.

To get only the final message in a file, use -o (--output-last-message) with a path. It writes to the file and also prints to stdout as usual. To fix the response format, pass a JSON Schema file to --output-schema. The final response then comes back as JSON that matches that schema.

codex exec "summarize the changes" -o ./summary.md

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

Standard input, resuming, and authentication

There are two ways to use standard input. If you give the instruction as an argument and pipe in data, the piped content is treated as reference material. If you omit the argument or use -, the whole of standard input becomes the prompt.

To continue a previous run, use resume. --last picks the most recent session, or you can pass a session ID.

By default, authentication reuses the login saved by the CLI. In CI, one option is to set CODEX_API_KEY for that single run only. The docs warn against putting OPENAI_API_KEY or CODEX_API_KEY in the environment of a whole job when the workflow runs code the repository controls, because build scripts or dependencies could read the key.

You need to run it inside a Git repository. The docs say to use --skip-git-repo-check only when the environment is safe. For GitHub Actions, they recommend openai/codex-action instead of installing the CLI yourself and passing a key.

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix" \
  | tee test-summary.md

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

Real examples

npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix" | tee test-summary.md

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

Common mistakes and when not to use it

• The default is read-only, so writing only "fix it" will not change anything. If you need edits, pass --sandbox workspace-write yourself.
• Do not use --sandbox danger-full-access on a personal computer. It is meant for isolated CI environments.
• Putting an API key in a whole CI job's environment lets build scripts and dependencies read it. Set it for that one run only.
• --full-auto, which appears in older posts, is no longer supported.
• Uploading ChatGPT login credentials (~/.codex/auth.json) to CI is an advanced option for trusted runners. Treat that file like a password, and the docs warn not to use it with public repositories.

FAQ