DEV Community

David Paluy
David Paluy

Posted on • Originally published at majesticlabs.dev

Codex CLI Developer Guide

#ai #codex #openai

Table of Contents

Quick Start

Install Codex CLI 

npm install -g @openai/codex@latest
Enter fullscreen mode Exit fullscreen mode

verify installation

codex --version
Enter fullscreen mode Exit fullscreen mode

Login with your OpenAI credentials

codex login
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Resume Codex Sessions

  1. Reopen your work. From the project directory you originally used, run: 
   codex resume
Enter fullscreen mode Exit fullscreen mode

Codex continues the last session where you left off so you can keep iterating immediately (Codex changelog).

  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
}
Enter fullscreen mode Exit fullscreen mode 
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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode
  • 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"
Enter fullscreen mode Exit fullscreen mode
  • 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"
Enter fullscreen mode Exit fullscreen mode
  • 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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
# Or via command line
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true "bundle install"
Enter fullscreen mode Exit fullscreen mode

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"
]
Enter fullscreen mode Exit fullscreen mode

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

Note: This guide was written for CLI Version: 0.42.0

Top comments (0)