Headless and Non-Interactive Mode

Your CI pipeline just failed. The test logs show a cryptic assertion error that would take a developer 30 minutes to diagnose. Instead, a post-failure workflow kicks off codex exec, which reads the repo, runs the tests, identifies the one-line fix, applies it, verifies the tests pass, and opens a PR — all in under five minutes with zero human intervention. This is codex exec in its element.

What You’ll Walk Away With

• Complete command patterns for codex exec including JSON output, structured schemas, and session resumption
• A production CI workflow that auto-fixes test failures and opens PRs
• Techniques for piping Codex output into other tools for downstream processing
• Security settings that give Codex exactly the permissions it needs and nothing more

Basic Usage

codex exec runs Codex without the interactive TUI. Progress streams to stderr; the final agent message prints to stdout.

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

# Pipe output to a file
codex exec "generate release notes for the last 10 commits" | tee release-notes.md

# Read prompt from stdin
echo "explain the authentication flow" | codex exec -

Permissions and Safety

By default, codex exec runs in a read-only sandbox. Escalate permissions deliberately:

# Allow file edits within the workspace
codex exec --full-auto "fix the failing tests"

# Allow broader access (only in isolated CI runners)
codex exec --sandbox danger-full-access "update system configuration"

Never use danger-full-access on shared runners

danger-full-access removes all sandboxing. Only use it inside an isolated CI runner or container where Codex cannot access other workloads, secrets, or network resources beyond what the task requires.

Machine-Readable JSON Output

For scripting and automation, use --json to get a JSONL stream of every event Codex emits:

codex exec --json "summarize the repo structure" | jq '.type'

Event types include thread.started, turn.started, turn.completed, turn.failed, and various item.* events for messages, commands, file changes, and MCP tool calls.

Sample output:

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"output_tokens":122}}

Structured Output with JSON Schema

When you need stable fields for downstream automation, use --output-schema:

schema.json

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "risk_areas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": { "type": "string" },
          "severity": { "type": "string" },
          "description": { "type": "string" }
        }
      }
    }
  },
  "required": ["project_name", "risk_areas"],
  "additionalProperties": false
}

codex exec "Analyze the codebase for security risks" \
  --output-schema ./schema.json \
  -o ./security-report.json

The output conforms to your schema, making it safe to parse programmatically.

Prompt: Generate a structured changelog

codex exec --output-schema ./changelog-schema.json -o changelog.json \
  "Generate a changelog for the last 20 commits. Group by category: features, fixes, refactors. Include the commit hash, author, and a one-line description for each entry."

Session Resumption

Chain multiple codex exec calls into a multi-stage pipeline:

# Stage 1: Analyze
codex exec "review the codebase for race conditions"

# Stage 2: Fix (resume the same session)
codex exec resume --last "fix the race conditions you found"

# Or resume a specific session
codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-xxxx "implement the plan"

CI Authentication

In CI environments, set CODEX_API_KEY as a secret:

CODEX_API_KEY=${{ secrets.OPENAI_API_KEY }} codex exec --json "triage open bug reports"

CODEX_API_KEY is only supported in codex exec. For interactive sessions, use codex login.

Prompt: Auto-fix CI failures in GitHub Actions

- name: Run Codex auto-fix
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  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."

Common Automation Patterns

Release Notes Generation

codex exec "Generate release notes for v2.1.0 based on commits since the v2.0.0 tag. Format as markdown with sections for Features, Fixes, and Breaking Changes." -o release-notes.md

Pre-Merge Quality Check

codex exec --json "Review the diff between HEAD and origin/main. Flag any breaking API changes, missing tests, or security issues. Output a pass/fail verdict." | jq '.item.text // empty' | tail -1

Nightly Codebase Health Report

codex exec --output-schema ./health-schema.json -o health-report.json \
  "Analyze code quality metrics: test coverage gaps, dead code, unused dependencies, and type safety issues. Prioritize by impact."

When This Breaks

• Git repository required: codex exec requires a Git repo by default. Use --skip-git-repo-check for non-Git directories, but only when you are sure the environment is safe.
• Prompt too long for stdin: Write long prompts to a file and pipe them: cat prompt.md | codex exec -
• JSON parsing failures: The JSONL stream emits one JSON object per line. Use jq with --slurp if you need to process the full stream as an array.
• Exit codes: codex exec exits non-zero on failure. Check $? in your scripts and handle failures explicitly.
• Token limits: Long-running exec sessions may hit context limits. Break complex work into multiple run + resume stages.

What’s Next

• GitHub Action — The pre-built GitHub Action wraps codex exec with additional CI conveniences
• Codex SDK — For more complex programmatic control beyond what codex exec offers
• Cost Management — Monitor credit usage for automated pipelines