Cheat Sheet

Reference intermediate

Codex CLI Command Reference

Basic Usage

# Start interactive session
codex

# Run with a specific prompt
codex "create a REST API for user management"

# Run with a specific model
codex --model gpt-5.4-mini "fix the failing tests"

# Run with full autonomy (no approval, full network)
codex --approval-policy never --sandbox danger-full-access "add input validation to all API routes"

Execution Mode Flags

Flag Policy Description
(default) Untrusted Shows proposed changes, asks for approval
--approval-policy on-request On-request Auto-applies file edits, asks before shell commands
--approval-policy never Never Everything automatic (combine with --sandbox danger-full-access for network)
--sandbox read-only Read-only sandbox Can read but not write files (exploration mode)

Model Selection

Flag Example Purpose
--model codex --model gpt-5.4-mini Use a specific model
--model codex --model gpt-5.5 Use most capable model

Common Command Patterns

# Fix a specific bug
codex "fix the TypeError in src/utils/parse.ts on line 42"

# Add a feature
codex "add pagination to the /api/users endpoint"

# Write tests
codex "write unit tests for src/lib/auth.ts covering all edge cases"

# Refactor
codex "refactor src/components/ to use the new design system components"

# Explain code
codex "explain how the caching layer works in src/lib/cache/"

# Debug
codex "the build fails with error [paste error]. Find and fix the cause"

Configuration File Locations

File Location Purpose
AGENTS.md Project root Project-specific instructions
~/.codex/config.toml Home directory Global user preferences
~/.codex/instructions.md Home directory Global instructions

Config File Options (config.toml)

# ~/.codex/config.toml
model = "gpt-5.4-mini"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[[providers]]
name = "openai"
env_key = "CODEX_API_KEY"

Environment Variables

Variable Purpose Example
CODEX_API_KEY API authentication sk-...
CODEX_HOME Config directory override ~/.codex
CODEX_MODEL Default model gpt-5.4-mini

Sandbox Capabilities

Codex runs in a sandboxed environment with:

Capability Available Notes
File read Yes Full project access
File write Yes Within project directory
Network (outbound) No Blocked by default
Run scripts Yes npm, python, bash, etc.
Install packages Yes Within sandbox
Git operations Yes Local only
System commands Limited Safe subset only

Task Decomposition Guide

Task Size Approach Example
One-liner Direct prompt "fix the typo in README"
Single file Prompt + context "add error handling to parse.ts"
Multi-file Feature description "add user authentication"
System-wide Step-by-step Break into 3-5 prompts

Output Interpretation

When Codex proposes changes, you will see:

┌─ src/lib/auth.ts ──────────────────────────────
│ + import { verify } from 'jsonwebtoken';
│ 
│   export function authenticate(token: string) {
│ -   return true; // TODO
│ +   try {
│ +     return verify(token, process.env.JWT_SECRET!);
│ +   } catch {
│ +     throw new AuthError('Invalid token');
│ +   }
│   }
└────────────────────────────────────────────────

Actions:

  • y / Enter - Accept changes
  • n - Reject changes
  • e - Edit the changes before accepting
  • q - Quit session

Tips for Effective Use

Tip Why
Start with --dry-run for risky tasks See plan before execution
Use specific file paths in prompts Narrows scope, better results
Paste error messages directly Gives AI exact diagnostic context
Run in untrusted policy first Build trust, then increase autonomy
Keep prompts focused (1 task) Reduces errors, easier to review
Reference test failures Codex can run tests to verify fixes

Common Workflows

Bug Fix Workflow:

codex "the test in tests/auth.test.ts is failing with: [error]. Fix the implementation."

Feature Workflow:

codex --approval-policy on-request "implement the TODO items in src/features/notifications/"

Cleanup Workflow:

codex --approval-policy never --sandbox danger-full-access "remove all unused imports and dead code in src/"

Documentation Workflow:

codex "add JSDoc comments to all exported functions in src/lib/"