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.
🚨 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.
# 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..."
| Model | ID | Use For |
|---|---|---|
| GPT-5.3 Codex | gpt-5.3-codex | ✅ Coding tasks (code review, debugging, writing code) |
| GPT-5.2 | gpt-5.2 | ✅ Everything else (research, writing, analysis) |
gpt-5.2-codex | ❌ DO NOT USE - Outdated (use gpt-5.3-codex) | |
gpt-5.1-codex-max | ❌ DO NOT USE - Outdated | |
o3 | ❌ DO NOT USE - Outdated | |
o4-mini | ❌ DO NOT USE - Outdated |
Remember: Always add -c model_reasoning_effort="high" to ALL calls.
| Flag | Description |
|---|---|
-m, --model | Model to use |
--json | Output events as JSON Lines to stdout |
-o, --output-last-message | Write final message to file |
--output-schema <path> | Enforce JSON schema on output |
--full-auto | Auto-approve + workspace-write sandbox |
-s, --sandbox | read-only, workspace-write, or danger-full-access |
-a, --ask-for-approval | untrusted, on-failure, on-request, or never |
--skip-git-repo-check | Allow running outside git repo |
-C, --cd <dir> | Set working directory |
-i, --image <file> | Attach image(s) to prompt |
--search | Enable web search tool |
-c, --config <key=val> | Override config values |
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 | Description |
|---|---|
thread.started | Session start with thread_id |
turn.started | New agent turn begins |
item.completed | Completed item (message, tool call, etc.) |
turn.completed | Turn finished with token usage stats |
turn.failed | Turn failed with error info |
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}`),
});
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"
# 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"
# 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
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"
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.
# 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)scripts/codex-parallel.js for Node.js concurrent executionreferences/configuration.md for all config options