Codex exec non-interactive mode runs Codex from a script, CI job or shell pipeline without opening the terminal interface. OpenAI’s non-interactive mode documentation names codex exec as the entry point: progress goes to standard error and only the final agent message goes to standard output, so the result is easy to redirect or pipe.

Applies to: Codex CLI non-interactive mode in OpenAI’s current documentation. Last checked: October 25, 2026.

On this page

Start a non-interactive run

Pass the task as one argument. This example is from the non-interactive mode page:

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

Because progress appears on stderr and the final agent message on stdout, the same page shows piping the result straight into a file:

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

That split matters in automation. A downstream command receives the final answer instead of a mixed stream of progress messages. The command reference also lists codex e as the short form of codex exec.

Pipe input as context or as the whole prompt

When you pipe data in and also give a prompt argument, OpenAI says the argument stays the instruction and the piped content becomes extra context. The documented log-triage example:

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

When another script generates the entire instruction, use the - sentinel so stdin becomes the prompt. From the advanced stdin piping section:

cat prompt.txt | codex exec -

Choose the sandbox before the run

By default, codex exec runs in a read-only sandbox, according to the permissions and safety section. OpenAI’s advice is to set the least permissions the workflow needs: --sandbox workspace-write allows edits, and --sandbox danger-full-access allows broader access. Use danger-full-access only in a controlled environment, such as an isolated CI runner or container.

The old --full-auto flag is no longer supported. The current docs point scripts to --sandbox workspace-write, or to --approve-for-me to route approval requests through automatic review with the workspace-write sandbox. The command reference adds that --approve-for-me conflicts with --sandbox and --yolo, and describes --dangerously-bypass-approvals-and-sandbox (--yolo) as dangerous, “only use inside an isolated runner”.

Two more switches help reproducible runs. --ignore-user-config skips $CODEX_HOME/config.toml, and --ignore-rules skips user and project execpolicy .rules files, as the non-interactive mode page describes.

For the broader permission model, see the Codex skip-permissions guide. The distinction to keep: --sandbox defines what commands may touch, while bypass flags remove safeguards and should not become a routine CI default.

Use JSON Lines when a program needs the event stream

Add --json when another program needs more than the final message:

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

OpenAI says stdout then becomes a JSON Lines stream, one JSON object per event. Event types include thread.started, turn.started, turn.completed, turn.failed, item.* and error. Item types include agent messages, reasoning, command executions, file changes, MCP tool calls, web searches and plan updates. The documentation’s sample stream looks like this:

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}

JSONL is a stream, not one JSON document. Read it line by line, and do not assume every line has the same fields. If a pipeline depends on exact event fields, pin the Codex CLI version on that runner.

Save only the final message

Use -o or --output-last-message when the next step needs the final answer in a file. The non-interactive mode page says this writes the final message to the file and still prints it to stdout. That is different from --json, which exposes the whole event stream. The command reference notes that a prompt is required when you use --output-last-message, --output-schema, --ephemeral or images.

Enforce a JSON schema for the final answer

For a stable machine-readable result, give Codex a JSON Schema with --output-schema. This is the documented example, saved as schema.json:

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

Then run Codex with the schema and write the final JSON response to disk:

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

OpenAI suggests this for automated workflows that need stable fields, such as job summaries, risk reports or release metadata. Keep the schema to the fields the next step actually consumes; additionalProperties: false rejects anything else.

Keep authentication scoped to the Codex step

codex exec reuses saved CLI authentication by default. For other automation environments, the authentication section says to set CODEX_API_KEY only for the Codex invocation that needs it:

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

Do not commit the key or place a real value in a script. OpenAI warns against setting OPENAI_API_KEY or CODEX_API_KEY as a job-level environment variable in workflows that check out or run repository-controlled code, because build scripts, tests, dependency lifecycle hooks or a compromised action in the same job can read it. For GitHub Actions, the same page recommends the Codex GitHub Action, which installs Codex, starts a Responses API proxy and runs Codex with a configurable safety strategy.

Resume a run or keep it ephemeral

Use --ephemeral when the run should not persist session rollout files to disk:

codex exec --ephemeral "triage this repository and suggest next steps"

For a two-stage workflow, the resume section shows a review followed by a fix:

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

You can also target a specific session with codex exec resume <SESSION_ID>. The command reference says --last picks the most recent session from the current working directory, and --all widens the search to sessions from any directory.

Account for the Git repository check

Codex requires commands to run inside a Git repository to prevent destructive changes, according to the non-interactive mode page. Override the check with codex exec --skip-git-repo-check only if you are sure the environment is safe. In a repository workflow, keeping the check gives the script a guard against running from the wrong directory.

The documented CI pattern

For GitHub Actions, OpenAI’s autofix example uses openai/codex-action rather than installing Codex in a shell step. The pattern it describes:

  1. Trigger a follow-up workflow when the main CI workflow completes with an error.
  2. Check out the failing commit with repository read permissions only.
  3. Run setup commands before Codex, without exposing the OpenAI API key to those steps.
  4. Run the Codex GitHub Action.
  5. Save Codex’s local changes as a patch artifact.
  6. In a separate job, apply the patch and open a pull request.

In that example the Codex job has only contents: read, and the job that opens the pull request gets write permissions but not OPENAI_API_KEY. The full workflow file is on the OpenAI page.

For configuration outside a single command, the Codex CLI customization guide covers terminal settings, while Codex MCP setup explains how configured servers enter an agent session.