Non-interactive mode

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Non-interactive mode lets you run Codex from scripts (for example, continuous integration (CI) jobs) without opening the interactive TUI. You invoke it with codex exec.

For flag-level details, see codex exec.

When to use codex exec

Use codex exec when you want Codex to:

• Run as part of a pipeline (CI, pre-merge checks, scheduled jobs).
• Produce output you can pipe into other tools (for example, to generate release notes or summaries).
• Fit naturally into CLI workflows that chain command output into Codex and pass Codex output to other tools.
• Run with explicit, pre-set sandbox and approval settings.

Basic usage

Pass a task prompt as a single argument:

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

While codex exec runs, Codex streams progress to stderr and prints only the final agent message to stdout. This makes it straightforward to redirect or pipe the final result:

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

Use --ephemeral when you don't want to persist session rollout files to disk:

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

If stdin is piped and you also provide a prompt argument, Codex treats the prompt as the instruction and the piped content as additional context.

This lets you generate input with one command and hand it directly to Codex:

curl -s https://jsonplaceholder.typicode.com/comments \
  | codex exec "format the top 20 items into a markdown table" \
  > table.md

For more advanced stdin piping patterns, see Advanced stdin piping.

Permissions and safety

By default, codex exec runs in a read-only sandbox. In automation, set the least permissions needed for the workflow:

• Allow edits: codex exec --sandbox workspace-write "<task>"
• Allow broader access: codex exec --sandbox danger-full-access "<task>"

Use danger-full-access only in a controlled environment (for example, an isolated CI runner or container).

Codex keeps codex exec --full-auto as a deprecated compatibility flag and prints a warning. Prefer the explicit --sandbox workspace-write flag in new scripts.

Use --ignore-user-config when you need a run that doesn't load $CODEX_HOME/config.toml, and --ignore-rules when you need to skip user and project execpolicy .rules files for a controlled automation environment.

If you configure an enabled MCP server with required = true and it fails to initialize, codex exec exits with an error instead of continuing without that server.

Make output machine-readable

To consume Codex output in scripts, use JSON Lines output:

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

When you enable --json, stdout becomes a JSON Lines (JSONL) stream so you can capture every event Codex emits while it's running. 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.

Sample JSON stream (each line is a JSON object):

{"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}}

If you only need the final message, write it to a file with -o <path>/--output-last-message <path>. This writes the final message to the file and still prints it to stdout (see codex exec for details).

Create structured outputs with a schema

If you need structured data for downstream steps, use --output-schema to request a final response that conforms to a JSON Schema. This is useful for automated workflows that need stable fields (for example, job summaries, risk reports, or release metadata).

schema.json

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

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

Example final output (stdout):

{
  "project_name": "Codex CLI",
  "programming_languages": ["Rust", "TypeScript", "Shell"]
}

Authenticate in automation

codex exec reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:

If your trusted cloud or CI runtime already receives short-lived workload tokens, use workload identity federation instead of storing an OpenAI credential.

Use API key auth

For GitHub Actions, use the Codex GitHub Action instead of installing and authenticating the CLI yourself. The action is designed to reduce API key exposure by installing Codex, starting a Responses API proxy, and running Codex with a configurable safety strategy.

Do not set OPENAI_API_KEY or CODEX_API_KEY as a job-level environment variable in workflows that check out or run repository-controlled code. Build scripts, tests, dependency lifecycle hooks, or a compromised action in the same job can read those environment variables.

For other automation environments, set CODEX_API_KEY only for the Codex invocation that needs it, and make sure no untrusted code runs in the same process environment.

To use a different API key for a single run, set CODEX_API_KEY inline: