Non-interactive mode

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 makes it easy to 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 --full-auto "<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).

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

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 CI

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

Use API key auth (recommended)

• Set CODEX_API_KEY as a secret environment variable for the job.
• Keep prompts and tool output in mind: they can include sensitive code or data.

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

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

CODEX_API_KEY is only supported in codex exec.

Resume a non-interactive session

If you need to continue a previous run (for example, a two-stage pipeline), use the resume subcommand:

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 ID with codex exec resume <SESSION_ID>.

Git repository required

Codex requires commands to run inside a Git repository to prevent destructive changes. Override this check with codex exec --skip-git-repo-check if you’re sure the environment is safe.

Common automation patterns

Example: Autofix CI failures in GitHub Actions

You can use codex exec to automatically propose fixes when a CI workflow fails. The typical pattern is:

1. Trigger a follow-up workflow when your main CI workflow completes with an error.
2. Check out the failing commit SHA.
3. Install dependencies and run Codex with a narrow prompt and minimal permissions.
4. Re-run the test command.
5. Open a pull request with the resulting patch.

Minimal workflow using the Codex CLI

The example below shows the core steps. Adjust the install and test commands to match your stack.

name: Codex auto-fix on CI failure

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  auto-fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
      FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ env.FAILED_HEAD_SHA }}
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: |
          if [ -f package-lock.json ]; then npm ci; else npm i; fi

      - name: Install Codex
        run: npm i -g @openai/codex

      - name: Authenticate Codex
        run: codex login --api-key "$OPENAI_API_KEY"

      - name: Run Codex
        run: |
          codex exec --full-auto --sandbox workspace-write \
            "Read the repository, run the test suite, identify the minimal change needed to make all tests pass, implement only that change, and stop. Do not refactor unrelated files."

      - name: Verify tests
        run: npm test --silent

      - name: Create pull request
        if: success()
        uses: peter-evans/create-pull-request@v6
        with:
          branch: codex/auto-fix-${{ github.event.workflow_run.run_id }}
          base: ${{ env.FAILED_HEAD_BRANCH }}
          title: "Auto-fix failing CI via Codex"

Alternative: Use the Codex GitHub Action

If you want to avoid installing the CLI yourself, you can run codex exec through the Codex GitHub Action and pass the prompt as an input.

Advanced stdin piping

When another command produces input for Codex, choose the stdin pattern based on where the instruction should come from. Use prompt-plus-stdin when you already know the instruction and want to pass piped output as context. Use codex exec - when stdin should become the full prompt.

Use prompt-plus-stdin

Prompt-plus-stdin is useful when another command already produces the data you want Codex to inspect. In this mode, you write the instruction yourself and pipe in the output as context, which makes it a natural fit for CLI workflows built around command output, logs, and generated data.

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

tail -n 200 app.log \
  | codex exec "identify the likely root cause, cite the most important errors, and suggest the next three debugging steps" \
  > log-triage.md

curl -vv https://api.example.com/health 2>&1 \
  | codex exec "explain the TLS or HTTP failure and suggest the most likely fix" \
  > tls-debug.md

gh run view 123456 --log \
  | codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \
  | pbcopy

gh run view 123456 --log \
  | codex exec "summarize the failure in 5 bullets for the pull request thread" \
  | gh pr comment 789 --body-file -

Use codex exec - when stdin is the prompt

If you omit the prompt argument, Codex reads the prompt from stdin. Use codex exec - when you want to force that behavior explicitly.

The - sentinel is useful when another command or script is generating the entire prompt dynamically. This is a good fit when you store prompts in files, assemble prompts with shell scripts, or combine live command output with instructions before handing the whole prompt to Codex.

cat prompt.txt | codex exec -

printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" \
  | codex exec -

generate_prompt.sh | codex exec - --json > result.jsonl