Non-Interactive Mode

codex exec runs Codex without the interactive TUI, making it ideal for CI/CD pipelines, scripts, and automation workflows. It streams events to stdout/stderr and exits automatically when the task completes.

Basic Usage#

# Simple task
codex exec "Add error handling to all API endpoints"

# With a specific model
codex exec -c model="gpt-5.3-codex" "Refactor the auth module"

Key Behaviors#

• No interaction required — Elicitation requests are auto-cancelled, approvals default to "never"
• Streaming output — Progress goes to stderr; the final agent message prints to stdout
• Auto-exit — Process exits when the turn completes (non-zero on failure)

JSON Output for Scripting#

Use --json to get machine-readable JSONL output:

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

In JSON mode, only protocol events go to stdout. Config summaries and warnings go to stderr, keeping the JSON stream clean for parsing.

Structured Output with --output-schema#

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

codex exec --output-schema '{
  "type": "object",
  "properties": {
    "summary": {"type": "string"},
    "risk_level": {"type": "string", "enum": ["low", "medium", "high"]},
    "files_changed": {"type": "array", "items": {"type": "string"}}
  }
}' "Analyze the security of this codebase"

This returns a JSON response conforming to your schema — useful for job summaries, risk reports, and release metadata.

CI/CD Integration#

Authentication#

In CI environments, set your API key as a secret:

env:
  CODEX_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Auto-Fix Pattern#

Automatically propose fixes when CI fails:

# 1. Detect CI failure
# 2. Run Codex with a narrow prompt
codex exec --sandbox danger-full-access \
  "The test suite failed. Fix the failing tests and verify they pass."

# 3. Check exit code
if [ $? -eq 0 ]; then
  git add -A
  git commit -m "fix: auto-fix failing tests"
  gh pr create --title "Auto-fix: CI test failures"
fi

### GitHub Action

The official Codex GitHub Action handles installation and proxy setup:

name: Codex Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          codex-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "Review this PR for correctness and security issues"

Useful Flags#

| Flag | Purpose | |------|---------| | --json | JSONL output for scripting | | --output-schema | Structured JSON response | | --output-last-message | Capture final summary alongside JSON events | | --full-auto | Low-friction mode (on-request approval + workspace-write) | | --skip-git-repo-check | Run in non-Git directories | | --sandbox danger-full-access | Full access (use in isolated envs only) |

MCP Server Requirements#

If you configure an MCP server with required = true and it fails to initialize, codex exec exits with an error instead of continuing without it. This prevents silent failures in automated pipelines.

Codex SDK Alternative#

For more control than exec provides, use the TypeScript SDK:

npm install @openai/codex-sdk

The SDK gives you programmatic control over sessions, tool calls, and agent behavior — useful for building custom automation tools, internal developer platforms, or complex multi-step pipelines.

Common Patterns#

Nightly Code Health Report#

codex exec --json --output-schema '{...}' \
  "Analyze the codebase for: dead code, unused dependencies, \
  security vulnerabilities, and test coverage gaps. \
  Output a structured report."

Pre-Commit Hook#

# .git/hooks/pre-commit
codex exec "Review the staged changes for obvious bugs" \
  && exit 0 || exit 1

Next Steps#

• GitHub Integration — Automated PR workflows
• Code Review — Interactive review features
• Safety Modes — Sandbox and approval settings