Codex CLI Developer Guide

Note: This guide was written for CLI Version: 0.42.0

Table of Contents

• Quick Start
• Resume Codex Sessions
• Shell Shortcuts
• Essential Configuration
  • Recommended config.toml
• Settings - Deep Dive
  • Sandbox Modes
  • Command-Line Overrides (-c flag)
  • YOLO Mode (–yolo)
  • Approval Policies
  • Profiles for Different Workflows
  • Verbosity - model_verbosity
  • Network Access
  • Environment Variables
• Security Best Practices

Quick Start

Install Codex CLI

npm install -g @openai/codex@latest

verify installation

codex --version

Login with your OpenAI credentials

codex login

Quick Examples

# Basic usage
codex "refactor this function to use dependency injection"

# With higher reasoning effort and detailed summary
codex -c model_reasoning_effort="high" -c model_reasoning_summary="detailed" "explain this complex algorithm"

# Automation in an isolated environment (bypasses sandbox/approvals)
codex --yolo "run tests and fix any failures"

# Generate Rails code when "dev" profile is defined
codex --profile dev "create a User model with devise authentication"

# Debug Rails issues
codex -c model_reasoning_effort="high" "fix this N+1 query in the users controller"

# Add features
codex "add pagination to the posts index using kaminari"

Resume Codex Sessions

1. Reopen your work. From the project directory you originally used, run:

   codex resume

Codex continues the last session where you left off so you can keep iterating immediately (Codex changelog, 2025-09-15).

1. Continue last session. Run codex resume --last to load the most recent conversation.

Shell Shortcuts

Keep frequently used flags close at hand with a reusable helper.

Add this to your .bashrc or .zshrc:

# Add to ~/.bashrc or ~/.zshrc
cdx() {
  local subcommand="$1"
  local base_model="gpt-5-codex"
  local base_args=(-m "$base_model" --search)

  if [[ -z "$subcommand" ]]; then
    codex "${base_args[@]}"
    return
  fi

  case "$subcommand" in
    help|-h|--help)
      cat <<'USAGE' >&2
Usage: cdx <prompt>
       cdx <subcommand> [args]

Subcommands:
  update                 install the latest Codex CLI
  5h                     high-effort reasoning run
  yolo                   run with --yolo (danger mode)
  dev|quick|auto|analyze switch to a named profile
USAGE
      return 0
      ;;
    update)
      npm install -g @openai/codex@latest
      ;;
    5h)
      shift
      codex -m gpt-5 -c model_reasoning_effort="high" --search "$@"
      ;;
    yolo)
      shift
      codex "${base_args[@]}" --yolo "$@"
      ;;
    dev|quick|auto|analyze)
      shift
      codex --profile "$subcommand" "$@"
      ;;
    *)
      codex "${base_args[@]}" "$@"
      ;;
  esac
}

Usage: cdx <prompt>
       cdx <subcommand> [args]

Subcommands:
  update                 install the latest Codex CLI
  5h                     high-effort reasoning run
  yolo                   run with --yolo (danger mode)
  dev|quick|auto|analyze switch to a named profile

examples

# Default dev workflow without bypassing safeguards
cdx "fix this N+1 query in the posts controller"

# Update Codex CLI
cdx update

# Switch to the dev profile on demand
cdx dev "implement OAuth authentication"

# High-reasoning call without yolo overrides
cdx 5h "optimize this complex SQL query with multiple joins"

# Explicitly opt into --yolo (automation-only)
cdx yolo "run tests and fix any failures"

Optional aliases

Add a few shortcuts after the function if you prefer profile-specific commands:

alias cdxdev='cdx dev'
alias cdxq='cdx quick'
alias cdxa='cdx auto'
alias cdxs='cdx analyze'

Essential Configuration

Recommended config.toml

Create ~/.codex/config.toml:

# Base settings
model = "gpt-5-codex"
model_provider = "openai"
sandbox_mode = "workspace-write"
approval_policy = "on-failure"
model_reasoning_effort = "high"

# Enable network for API calls and package installation
[sandbox_workspace_write]
network_access = true

# Safe environment variables
[shell_environment_policy]
inherit = "core"
experimental_use_profile = true

# Development profile
[profiles.dev]
model_reasoning_effort = "high"
model_verbosity = "high"
sandbox_mode = "workspace-write"
approval_policy = "on-failure"

# Quick tasks profile
[profiles.quick]
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"
approval_policy = "never"

# Analysis profile
[profiles.analyze]
sandbox_mode = "read-only"
model_reasoning_effort = "high"
approval_policy = "never"

# Automation profile
[profiles.auto]
sandbox_mode = "danger-full-access"
approval_policy = "never"
model_reasoning_summary = "auto"

Other providers profiles examples:

[model_providers.lms]
name = "LM Studio"
base_url = "http://localhost:1234/v1"

[profiles.qwen3-coder-30b-lms]
model_provider = "lms"
model = "qwen/qwen3-coder-30b"
model_reasoning_effort = "high"
approval_policy = "on-failure"

Settings - Deep Dive

Sandbox Modes

Controls what Codex can access and modify on your system:

read-only - Code Analysis Only

codex --sandbox read-only "explain what this codebase does"

• Reads files anywhere
• Cannot modify files or run commands
• Perfect for code review and exploration

workspace-write - Development Mode (Default)

codex --sandbox workspace-write "add error handling to this controller"

• Reads files anywhere
• Writes only in current directory
• Ideal for active development

danger-full-access - No Restrictions

codex --sandbox danger-full-access "set up the entire development environment"

• Complete system access
• Use only in Docker containers or disposable environments

Command-Line Overrides (-c flag)

Override any config setting temporarily:

# High reasoning for complex problems
codex -c model_reasoning_effort="high" "optimize this database query"

# Low verbosity for simple tasks
codex -c model_verbosity="low" "fix this syntax error"

# Enable network access on demand
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true "install missing gems"

# Skip all approvals
codex -c approval_policy="never" "run the test suite"

YOLO Mode (–yolo)

Bypasses all safety mechanisms - use with extreme caution:

# Equivalent to: --sandbox danger-full-access --approval-policy never
codex --yolo "deploy to staging and run integration tests"

Safe YOLO usage: - Inside Docker containers - Dedicated development VMs - When you need complete automation - Always have backups and version control

Approval Policies

Control when Codex asks for permission:

# Never ask (automation)
codex -c approval_policy="never" "fix linting issues"

# Ask before untrusted operations (default-ish)
codex -c approval_policy="on-request" "install dependencies"

# Ask only when commands fail
codex -c approval_policy="on-failure" "run migrations"

# Ask before every command
codex -c approval_policy="untrusted" "modify production config"

Profiles for Different Workflows

Use profiles to switch between configurations:

# High-reasoning development
codex --profile dev "implement OAuth authentication"

# Quick fixes
codex --profile quick "fix typo in variable name"

# Safe analysis
codex --profile analyze "review this code for security issues"

# Full automation
codex --profile auto "run tests, fix failures, commit changes"

Verbosity - model_verbosity

Control how much detail Codex provides:

• “low” – terse responses suited to automation or CI pipelines
• “medium” – balanced explanations for everyday development (default)
• “high” – expanded context and commentary for deep dives

# Detailed explanations
codex -c model_verbosity="high" "walk me through this design pattern"

# Request a richer reasoning summary when available
codex -c model_reasoning_summary="detailed" "explain this complex algorithm"

# Minimal output for automation
codex -c model_reasoning_summary="concise" -c model_verbosity="low" "fix syntax"

model_verbosity accepts only low, medium (the default), or high; choose the level that matches how much explanation you want in the response. Pair it with model_reasoning_summary, which controls the optional reasoning summary (auto by default, with concise or detailed as alternatives) so you can surface or hide the model’s step-by-step reasoning for different workflows.

Network Access

Enable network for package installation and API calls:

# In config.toml
[sandbox_workspace_write]
network_access = true

# Or via command line
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true "bundle install"

Environment Variables

Control which shell variables Codex inherits:

[shell_environment_policy]
inherit = "core"  # PATH, HOME, USER, SHELL, etc.
experimental_use_profile = true  # Load .bashrc, .zshrc

# Whitelist specific variables
include_only = [
  "PATH",
  "HOME",
  "RAILS_ENV",
  "DATABASE_URL"
]

# Blacklist sensitive variables
exclude = [
  "*_API_KEY",
  "*_SECRET",
  "PASSWORD"
]

Security Best Practices

1. Never use YOLO in production environments
2. Use read-only for code review and exploration
3. Use workspace-write for active development
4. Keep sensitive environment variables out of include_only
5. Test configurations in safe environments first
6. Use version control before running destructive operations