# Codex CLI

> Use OpenAI Codex CLI in non-interactive mode for automated code analysis, review, and programmatic task execution. Trigger on requests like "use Codex to analyze", "run codex exec", "codex code review", or when users want AI-powered code analysis without interactive prompts. Ideal for automation workflows, code quality checks, and generating structured analysis reports.

- Skill: `benjaming/codex-cli` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add benjaming/codex-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/benjaming/codex-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: BenjaminG (https://skillmd.com/u/benjaming)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/benjaming/codex-cli

---


# Codex CLI Non-Interactive Mode

## Overview

Execute OpenAI's Codex CLI in non-interactive mode (`codex exec`) to automate code analysis, reviews, and other development tasks without requiring user approvals. The tool operates with configurable safety modes and supports structured outputs for integration into automation pipelines.

## When to Use This Skill

Use Codex CLI when the user requests:
- Code analysis or architectural reviews using AI assistance
- Automated code quality checks or security audits
- Generating reports (changelogs, documentation, etc.) from code
- Multi-step analysis workflows that benefit from persistent context
- Integration with automation pipelines requiring structured output

**Trigger phrases:** "use Codex to...", "run codex exec", "codex analyze", "have codex review"

## Core Capabilities

### 1. Safety Mode Selection

Choose the appropriate safety mode based on task requirements:

**Read-Only (Default)** - For analysis and review tasks:
```bash
codex exec "Analyze the authentication flow and identify potential security issues"
```

**Full Automation** - When file modifications are needed:
```bash
codex exec --full-auto "Refactor the user service to follow SOLID principles"
```

**Unrestricted Mode** - Only when network access is required:
```bash
codex exec --sandbox danger-full-access "Test API endpoints and validate responses"
```

**Decision Guidelines:**
- Start with read-only for initial exploration
- Use --full-auto when the user explicitly requests code changes
- Reserve unrestricted mode for tasks requiring network operations
- Always inform the user which mode is being used and why

### 2. Output Handling

Configure output format based on downstream requirements:

**Default (Pipe-Friendly)**
```bash
codex exec "Generate changelog from last 10 commits" > changelog.md
```
Activity logs to stderr, final output to stdout.

**Save to File**
```bash
codex exec "Review code for type errors" -o review-report.txt
```

**JSON Streaming (JSONL to stdout)**
```bash
codex exec --json "Comprehensive security audit" 2>&1 | tee audit-log.jsonl
```
With `--json`, stdout becomes a JSONL stream of every event (stderr retains progress output). Events include `thread.started`, `turn.started`, `turn.completed`, `item.started`, `item.completed`, and `error`. Item types: `agent_message`, `command_execution`, `file_change`, `reasoning`, `mcp_tool_call`, `web_search`, `plan_update`.

Filter specific events:
```bash
# Extract only agent messages
codex exec --json "<task>" | jq 'select(.type == "item.completed" and .item.type == "agent_message")'

# Track token usage per turn
codex exec --json "<task>" | jq 'select(.type == "turn.completed") | .usage'
```

**Structured Schema Output**
```bash
codex exec "Find all TODO comments with context" --output-schema todo-schema.json
```
Enforces specific JSON structure for automation pipelines.

### 3. Session-Based Workflows

Sessions are persisted to disk by default, enabling resume across invocations and environments.

```bash
# Initial analysis
codex exec "Analyze the codebase architecture"
# Returns session ID, e.g., session_abc123

# Follow-up with context
codex exec resume --last "Now identify performance bottlenecks in the identified critical paths"

# Or resume specific session
codex exec resume session_abc123 "Generate refactoring recommendations"
```

**Taking over a non-interactive session:**
Resume a session started elsewhere (e.g., CI pipeline) from your local machine:
```bash
# In CI: run analysis, capture session ID from output
SESSION_ID=$(codex exec --json "Audit dependencies for vulnerabilities" 2>/dev/null | jq -r 'select(.type=="thread.started") | .session_id')

# Locally: take over with full context preserved
codex exec resume "$SESSION_ID" "Fix the critical vulnerabilities you found" --full-auto
```

**Ephemeral sessions** — use `--ephemeral` to skip persisting session data to disk (useful for one-shot CI tasks that won't be resumed):
```bash
codex exec --ephemeral "Generate test coverage report" -o coverage.md
```

**Notes:**
- Behavior flags (--full-auto, --sandbox, etc.) must be re-specified on resume
- Session data is stored locally; cross-machine resume requires shared storage or transferring session files

### 4. Automation Integration

Integrate Codex into CI/CD or development workflows:

```bash
# Code review in PR pipeline
codex exec --json "Review uncommitted changes for bugs and style issues" \
  --output-schema review-schema.json > review.json

# Generate documentation
codex exec "Generate API documentation from comments" -o api-docs.md

# Security scanning
codex exec "Scan for OWASP Top 10 vulnerabilities" --json 2>&1 | \
  jq 'select(.type=="item.completed" and .item.type=="agent_message")'
```

## Task Execution Patterns

### Code Analysis Task
```bash
# User asks: "Use Codex to analyze our error handling patterns"
codex exec "Analyze error handling patterns across the codebase. Identify inconsistencies, anti-patterns, and suggest improvements."
```

### Code Review Task
```bash
# User asks: "Have Codex review the recent changes"
codex exec --full-auto "Review git diff for the last commit. Check for bugs, security issues, and code quality problems."
```

### Report Generation Task
```bash
# User asks: "Generate a changelog using Codex"
codex exec "Generate a changelog from commits since last release tag. Group by feature, bugfix, and breaking changes." -o CHANGELOG.md
```

### Multi-Step Investigation
```bash
# User asks: "Use Codex to investigate the performance issues"
codex exec "Profile the application and identify performance bottlenecks"
# Review results, then:
codex exec resume --last "Deep dive into the database query performance issues you identified"
```

## Important Considerations

### Git Repository Requirement
Codex requires a Git repository to track changes safely. Override only when necessary:
```bash
codex exec --skip-git-repo-check "<task>"
```

### Authentication
Use default Codex CLI credentials or override:
```bash
CODEX_API_KEY=your-key-here codex exec "<task>"
```

### Error Handling
- Check exit codes: `$?` for success/failure
- Stderr contains activity logs and errors
- JSON mode provides structured error events

### Model Selection
Codex CLI defaults to appropriate models based on platform. Explicit model selection happens in interactive mode only.

## Reference Documentation

For detailed command syntax, all available flags, and advanced use cases, consult:
- `references/codex-exec-reference.md` - Comprehensive command reference

Use `rg` to search reference documentation when specific flag information is needed:
```bash
rg "resume" references/codex-exec-reference.md
```

## Best Practices

1. **Always explain the chosen safety mode** to the user
2. **Start conservative** (read-only) and escalate permissions only when needed
3. **Capture session IDs** when planning multi-step workflows
4. **Use structured outputs** (--output-schema) for automation reliability
5. **Monitor JSON streams** for long-running tasks to provide progress updates
6. **Combine with shell tools** (jq, grep, etc.) for post-processing
7. **Preserve context** through session resume for complex investigations