codex-cli-scripting

name: codex-cli-scripting description: Write scripts that programmatically call OpenAI's Codex CLI in headless mode. Use when writing automation scripts, building batch processing pipelines, running parallel Codex API calls, integrating Codex into shell/Node.js/Python scripts, parsing Codex CLI JSON output, or answering questions about Codex CLI models, flags, and configuration. Use the --search flag for fact-checking, research, literature reviews, or any task requiring up-to-date information.

Codex CLI Scripting

🚨 CRITICAL: NEVER USE OLDER MODELS 🚨

ONLY use these models:

• gpt-5.3-codex — for coding tasks (code review, debugging, writing code, etc.)
• gpt-5.2 — for everything else (research, writing, analysis, etc.)

NEVER use: o3, o4-mini, gpt-5.1-codex-max, gpt-5.2-codex, or any other older model.

ALWAYS set reasoning effort explicitly: -c model_reasoning_effort="high" (or "xhigh")

This applies to ALL calls regardless of task type. Non-negotiable.

Quick Reference

Headless Command Syntax

# Basic headless call (ALWAYS include model + reasoning effort)
codex exec -m gpt-5.3-codex -c model_reasoning_effort="high" "Your prompt here"

# With explicit xhigh reasoning
codex exec -m gpt-5.3-codex -c model_reasoning_effort="xhigh" "prompt"

# JSON output (for parsing) - streams events as JSONL
codex exec --json "prompt"

# Save final message to file
codex exec -o output.txt "prompt"

# Stdin input
echo "code to review" | codex exec -
cat file.py | codex exec "Review this code" -

# Full auto mode (file edits + auto-approval)
codex exec --full-auto "Create a test file"

# Danger mode (full access including network)
codex exec --sandbox danger-full-access "Run the build"

# Skip git repo requirement
codex exec --skip-git-repo-check "prompt"

# Enable web search (for current information)
codex exec --search "What are the latest Node.js security updates?"

# Combine flags (always include model + reasoning)
codex exec --json --search -m gpt-5.3-codex -c model_reasoning_effort="high" "Research best practices for..."

Available Models

Remember: Always add -c model_reasoning_effort="high" to ALL calls.

Key Flags

JSON Output Schema

When using --json, events are newline-delimited JSON (JSONL):

{"type":"thread.started","thread_id":"019b21c4-5768-7892-a764-199557ebabfa"}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"response here"}}
{"type":"turn.completed","usage":{"input_tokens":7869,"cached_input_tokens":7680,"output_tokens":5}}

Event Types

Parallel Execution Pattern (Node.js)

Use scripts/codex-parallel.js for concurrent calls:

const { callCodex, callCodexParallel } = require('./scripts/codex-parallel');

// Single call
const result = await callCodex('Your prompt');
console.log(result.response);

// Parallel calls with concurrency control
const results = await callCodexParallel([
  'Prompt 1',
  'Prompt 2',
  'Prompt 3',
], {
  concurrency: 5,           // Max simultaneous calls
  model: 'gpt-5.3-codex',
  search: true,             // Enable web search
  onProgress: ({ completed, total }) => console.log(`${completed}/${total}`),
});

Web Search Patterns

Use --search to enable web search for up-to-date information, fact-checking, research, and literature reviews:

# Research current best practices
codex exec --search "What are current security best practices for React 18?"

# Fact-check claims or statements
codex exec --search "Fact check: Does Python 3.13 have a no-GIL mode?"

# Conduct literature review
codex exec --search "Survey recent papers on transformer architecture improvements"

# Research emerging technologies
codex exec --search "Research current state of WebGPU adoption and browser support"

# Get latest package versions
codex exec --search --json "Find the latest stable version of TypeScript"

# Compare current technologies
codex exec --search -m gpt-5.2 -c model_reasoning_effort="high" "Compare Vite vs Webpack in 2025"

# Verify documentation or API changes
codex exec --search "Check if React useEffect cleanup behavior changed in recent versions"

# Troubleshoot with latest docs
echo "error log" | codex exec --search "Debug this error" -

# Research and generate code
codex exec --search --full-auto "Create a component using latest Next.js patterns"

Shell Script Patterns

# Batch processing files
for file in src/*.py; do
  codex exec --json -m gpt-5.3-codex -c model_reasoning_effort="high" \
    "Review this code" < "$file" > "reviews/$(basename "$file").json"
done

# Extract just the response text from JSON output
codex exec --json "What is 2+2?" 2>/dev/null | \
  jq -r 'select(.type=="item.completed") | .item.text'

# Generate commit message from diff
git diff --cached | codex exec "Write a concise commit message" -

# Code review pipeline
cat src/main.py | codex exec --json \
  "Review for security issues" - 2>/dev/null | \
  jq -r 'select(.type=="item.completed") | .item.text' > review.txt

# Structured output with JSON schema
codex exec --output-schema schema.json "Extract data from this text"

Session Management

# Resume the most recent session
codex exec resume --last "Continue with the next task"

# Resume a specific session by ID
codex exec resume <SESSION_ID> "Next instruction"

# List and resume interactively
codex resume

Configuration

Config file location: ~/.codex/config.toml

# Default model
model = "gpt-5.3-codex"

# Reasoning effort: low, medium, high, xhigh (always use high or xhigh)
model_reasoning_effort = "high"

# MCP servers
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

# Project-specific settings
[projects."/path/to/project"]
trust_level = "trusted"

Override config via CLI:

codex exec -c model="o3" -c model_reasoning_effort="high" "prompt"

Authentication

Set the CODEX_API_KEY environment variable to override default credentials:

CODEX_API_KEY=your-api-key codex exec --json "task"

Default: Uses stored OAuth credentials from codex login.

Feature Flags

# List all features
codex features list

# Enable/disable features
codex exec --enable parallel --disable warnings "prompt"

Key features:

• parallel - Parallel tool execution (stable, default: true)
• shell_tool - Shell command execution (stable, default: true)
• web_search_request - Web search capability (stable, default: false)
• undo - Undo support (stable, default: true)

References

• Parallel execution helper: See scripts/codex-parallel.js for Node.js concurrent execution
• Configuration reference: See references/configuration.md for all config options