Skip to main content

​
Syntax

codex exec [OPTIONS] [PROMPT]

​
Description

The exec command runs Codex non-interactively, making it ideal for automation, CI/CD pipelines, and scripting. It reads a prompt, executes the task, and exits when complete.
Use codex exec when you need:
  • Headless operation (no interactive TUI)
  • Structured JSON output
  • Automation in scripts or CI/CD
  • Output piped to other commands

​
Usage

​
Basic Execution

codex exec "explain this codebase"
codex exec "run tests and fix any failures"

​
From stdin

Read the prompt from stdin: 
echo "add error handling" | codex exec
codex exec < prompt.txt
codex exec -  # Force reading from stdin

​
JSON Output

Get structured JSON events: 
codex exec --json "list all API endpoints" > output.jsonl
codex exec --json "analyze code quality" | jq '.msg'

​
Options

​
PROMPT
string
Prompt to send to Codex. Use - to read from stdin.

​
Output

​
--json
boolean
Output events as JSON Lines (JSONL). Each line is a valid JSON object representing an event.
​
-o, --output-last-message
path
Write the final message to a file. Useful for capturing Codex’s response.
​
--output-schema
path
Path to a JSON schema file. Codex will format its final output to match this schema.

​
Model & Provider

​
-m, --model
string
AI model to use (e.g., gpt-4.1, o4-mini).
​
--oss
boolean
Use open-source/local model provider.
​
--local-provider
string
OSS provider: ollama, lmstudio.

​
Approval & Sandbox

​
--full-auto
boolean
Run in full-auto mode. No approvals required.
​
--sandbox
string
Sandbox mode: workspace-write, workspace-read-network-write, read-only, danger-full-access.
​
--dangerously-bypass-approvals-and-sandbox
boolean
Skip all approvals and sandbox restrictions. Use with extreme caution.

​
Input

​
-i, --images
string
Comma-separated list of image paths.
​
--add-dir
path
Additional writable directories (repeatable).

​
Progress Indicators

​
--color
string
Control colored output: auto, always, never.
​
--progress-cursor
boolean
Show progress indicator. Auto-detected by default.

​
Session

​
-C, --cwd
path
Working directory.
​
--ephemeral
boolean
Don’t save session to history.
​
--skip-git-repo-check
boolean
Skip Git repository check.

​
Examples

​
CI/CD Integration

# GitHub Actions
- name: Update changelog
  run: |
    codex exec --full-auto "update CHANGELOG.md for v2.0.0"

# GitLab CI
script:
  - codex exec "run security scan and create report"

​
JSON Output for Processing

# Get JSON events
codex exec --json "analyze code coverage" > coverage-analysis.jsonl

# Extract specific fields
codex exec --json "list dependencies" | jq -r 'select(.msg.type=="text") | .msg.content'

# Save final message
codex exec -o response.txt "summarize recent changes"

​
Structured Output Schema

# Define schema
cat > schema.json <<EOF
{
  "type": "object",
  "properties": {
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "method": { "type": "string" }
        }
      }
    }
  }
}
EOF

# Run with schema
codex exec --output-schema schema.json "list all API endpoints" | jq .

​
Automation Scripts

#!/bin/bash
# daily-tasks.sh

# Update documentation
codex exec "update API documentation based on recent changes"

# Run tests
codex exec "run test suite and report failures" -o test-results.txt

# Check code quality
codex exec --json "analyze code quality" > quality-report.jsonl

​
Reading from stdin

# From echo
echo "add logging to main.ts" | codex exec

# From file
codex exec < task-description.txt

# From here-doc
codex exec <<EOF
Refactor the authentication module:
1. Add rate limiting
2. Improve error handling
3. Add unit tests
EOF

​
Different Models

# Use GPT-4.1 for complex tasks
codex exec -m gpt-4.1 "design microservices architecture"

# Use local Ollama for quick tasks
codex exec --oss --local-provider ollama "format this code"

​
JSON Output Format

When using --json, each line is a JSON object with this structure: 
{
  "msg": {
    "type": "text",
    "content": "Processing your request..."
  },
  "timestamp": "2026-02-28T10:30:00Z"
}
Common event types:
  • text - Text messages from Codex
  • exec_approval_request - Requesting approval to run a command
  • apply_patch_approval_request - Requesting approval to modify files
  • turn_complete - Task completed
  • error - Error occurred

​
Exit Codes

  • 0 - Success
  • 1 - Error occurred (failed commands, API errors, etc.)