Non-interactive mode

Non-interactive mode allows you to run Codex without the terminal UI, making it ideal for automation, scripts, and CI/CD pipelines. Use the exec and review commands for headless execution.

The exec command

Run a one-off task without the interactive TUI:

codex exec "run the test suite and fix any failures"

echo "analyze code coverage and suggest improvements" | codex exec

codex exec - <<EOF
Please review the authentication flow and:
1. Check for security issues
2. Add rate limiting
3. Improve error messages
EOF

Output formats

By default, exec provides human-readable output with progress indicators. For programmatic use, enable JSON output:

codex exec --json "run tests" > events.jsonl

This streams JSONL (JSON Lines) events that you can parse:

{"method":"turn/started","params":{"turn":{"id":"turn_123","status":"inProgress"}}}
{"method":"item/started","params":{"item":{"type":"agentMessage","id":"msg_1"}}}
{"method":"item/agentMessage/delta","params":{"itemId":"msg_1","delta":"Running"}}
{"method":"item/agentMessage/delta","params":{"itemId":"msg_1","delta":" tests..."}}
{"method":"item/completed","params":{"item":{"type":"agentMessage","id":"msg_1","text":"Running tests..."}}}
{"method":"turn/completed","params":{"turn":{"id":"turn_123","status":"completed"}}}

Exit codes

codex exec returns meaningful exit codes for automation:

Exit Code	Meaning
`0`	Success - task completed
`1`	General error
`2`	Authentication failed
`3`	Configuration error
`4`	Model/API error
`130`	Interrupted by user (Ctrl+C)

Command options

codex exec [OPTIONS] [PROMPT]

Options:
  -m, --model <MODEL>              Model to use (e.g., gpt-5.2-codex)
  -s, --sandbox <MODE>             Sandbox mode: read-only, workspace-write, danger-full-access
  -C, --cd <DIR>                   Working directory
  -i, --image <FILE>               Attach images (comma-separated)
      --json                       Output JSONL events
      --ephemeral                  Don't persist session to disk
      --output-schema <FILE>       JSON Schema for structured output
  -o, --output-last-message <FILE> Write final agent message to file
      --color <WHEN>               Color output: auto, always, never
      --full-auto                  Auto-approve with workspace-write sandbox
      --yolo                       Bypass all approvals (DANGEROUS)

The review command

Request an automated code review from Codex:

codex review

codex review abc1234

codex review --base main

codex review --instructions "Focus on security and performance"

Review targets

The review command supports multiple targets:

Uncommitted
Commit
Base branch
Custom

Review staged, unstaged, and untracked files:

codex review

Review a specific commit by SHA:

codex review 1234567

Review changes since branching from main:

codex review --base main

Provide free-form instructions:

codex review --instructions "Check for SQL injection vulnerabilities"

Review output

Reviews produce structured feedback:

╭─ Code Review ──────────────────────────────────────────╮
│ Overall: The changes look solid with minor suggestions │
│                                                         │
│ Findings:                                              │
│                                                         │
│ • Consider adding error handling — auth.ts:42-55       │
│   The login function doesn't handle network failures    │
│                                                         │
│ • Extract magic number — config.ts:18                  │
│   Use a named constant for the timeout value           │
│                                                         │
│ • Add input validation — api.ts:91                     │
│   Validate user input before database queries          │
╰─────────────────────────────────────────────────────────╯

Resume and continue

Non-interactive mode supports resuming previous sessions:

codex exec resume --last "add more test cases"

codex exec resume thr_abc123 "now deploy to staging"

codex exec --json resume --last

CI/CD integration

Codex is designed to integrate seamlessly into automated workflows.

GitHub Actions

name: Codex Auto-fix
on: [push]

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Codex
        run: |
          curl -fsSL https://codex.openai.com/install.sh | sh
          echo "$HOME/.codex/bin" >> $GITHUB_PATH
      
      - name: Run tests and auto-fix
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec --full-auto --json "run tests and fix any failures" | tee results.jsonl
      
      - name: Check success
        run: |
          if [ $? -ne 0 ]; then
            echo "Codex failed to fix tests"
            exit 1
          fi

name: Codex Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Install Codex
        run: |
          curl -fsSL https://codex.openai.com/install.sh | sh
          echo "$HOME/.codex/bin" >> $GITHUB_PATH
      
      - name: Run review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex review --base origin/main -o review.txt
      
      - name: Post review
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.txt', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: '## Codex Review\n\n' + review
            });

GitLab CI

.gitlab-ci.yml

codex-review:
  stage: test
  image: ubuntu:latest
  before_script:
    - curl -fsSL https://codex.openai.com/install.sh | sh
    - export PATH="$HOME/.codex/bin:$PATH"
  script:
    - codex review --base origin/main --json > review.jsonl
  artifacts:
    paths:
      - review.jsonl
    expire_in: 1 week
  only:
    - merge_requests

Jenkins

Jenkinsfile

pipeline {
    agent any
    
    environment {
        OPENAI_API_KEY = credentials('openai-api-key')
    }
    
    stages {
        stage('Install Codex') {
            steps {
                sh 'curl -fsSL https://codex.openai.com/install.sh | sh'
            }
        }
        
        stage('Run Tests') {
            steps {
                sh '''
                    export PATH="$HOME/.codex/bin:$PATH"
                    codex exec --full-auto --json "run the test suite" > results.jsonl
                '''
            }
        }
        
        stage('Analyze Results') {
            steps {
                script {
                    def results = readJSON file: 'results.jsonl'
                    // Process JSONL events
                }
            }
        }
    }
}

Structured output

Constrain the agent’s response to a specific JSON schema:

codex exec \
  --output-schema schema.json \
  --json \
  "analyze test coverage"

schema.json:

{
  "type": "object",
  "properties": {
    "coverage_percentage": { "type": "number" },
    "uncovered_files": {
      "type": "array",
      "items": { "type": "string" }
    },
    "recommendations": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["coverage_percentage", "uncovered_files", "recommendations"],
  "additionalProperties": false
}

The final agent message will conform to this schema.

Ephemeral sessions

Run without persisting to disk:

codex exec --ephemeral "quick calculation: 2^16"

Useful for:

One-off queries
Sensitive data that shouldn’t be logged
Reducing disk I/O in high-volume scenarios

Automation best practices

Use --full-auto for trusted environments

In sandboxed CI runners, use --full-auto to auto-approve operations:

codex exec --full-auto "install deps and run tests"

Enable JSON output for parsing

Always use --json in automation to get structured events:

codex exec --json "task" | jq -r 'select(.method=="turn/completed")'

Check exit codes

Handle failures gracefully in scripts:

if ! codex exec "run tests"; then
  echo "Tests failed"
  exit 1
fi

Capture final output

Use --output-last-message for the agent’s final response:

codex exec -o result.txt "summarize changes"
cat result.txt

Never use --yolo (dangerously bypass approvals) in production or on untrusted inputs. This disables all safety checks.

Parsing JSONL output

Using jq

# Extract all agent messages
codex exec --json "task" | jq -r 'select(.method=="item/agentMessage/delta") | .params.delta'

# Get final turn status
codex exec --json "task" | jq -r 'select(.method=="turn/completed") | .params.turn.status'

# Count commands executed
codex exec --json "task" | jq -r 'select(.method=="item/started" and .params.item.type=="commandExecution")' | wc -l

Using Python

import json
import subprocess

proc = subprocess.Popen(
    ["codex", "exec", "--json", "run tests"],
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True
)

for line in proc.stdout:
    event = json.loads(line)
    if event["method"] == "item/commandExecution/outputDelta":
        print(event["params"]["delta"], end="")
    elif event["method"] == "turn/completed":
        print(f"\nStatus: {event['params']['turn']['status']}")

Non-interactive mode

The exec command

Output formats

Exit codes

Command options

The review command

Review targets

Review output

Resume and continue

CI/CD integration

GitHub Actions

GitLab CI

Jenkins

Structured output

Ephemeral sessions

Automation best practices

Parsing JSONL output

Using jq

Using Python

Next steps

Interactive mode

Sandboxing

​The exec command

​Output formats

​Exit codes

​Command options

​The review command

​Review targets

​Review output

​Resume and continue

​CI/CD integration

​GitHub Actions

​GitLab CI

​Jenkins

​Structured output

​Ephemeral sessions

​Automation best practices

​Parsing JSONL output

​Using jq

​Using Python

​Next steps

Interactive mode

Sandboxing

The exec command

Output formats

Exit codes

Command options

The review command

Review targets

Review output

Resume and continue

CI/CD integration

GitHub Actions

GitLab CI

Jenkins

Structured output

Ephemeral sessions

Automation best practices

Parsing JSONL output

Using jq

Using Python

Next steps