← All cheat sheets

Codex CLI

Getting Started {.cols-2}

Install & Run {.row-span-2}

npm (recommended)

$ npm install -g @openai/codex
$ npm install -g @openai/codex@latest   # upgrade

Homebrew (macOS)

$ brew install codex

First run

$ codex                          # launch interactive TUI
$ codex "Explain this codebase"  # with initial prompt

On first run you'll be prompted to sign in via ChatGPT or an API key.

Shell completions

# Zsh – add to ~/.zshrc
$ eval "$(codex completion zsh)"

# Bash – add to ~/.bashrc
$ eval "$(codex completion bash)"

# Fish
$ codex completion fish | source

Platform Support

{.show-header}

Authentication

$ codex login                # ChatGPT OAuth
$ codex login --device-auth  # device flow
# Pipe API key from env
$ printenv OPENAI_API_KEY | codex login --with-api-key
$ codex login status         # check auth state
$ codex logout               # remove credentials

Subcommands {.cols-3}

Command Reference {.col-span-2 .row-span-2}

{.show-header}

Exec (Non-interactive)

# Basic non-interactive run
$ codex exec "Fix the race condition"
$ codex e "Add unit tests for utils"

# Prompt from stdin
$ echo "Explain main.go" | codex exec -

# Prompt-plus-stdin (0.118+): pipe data AND pass a prompt
$ cat error.log | codex exec "Diagnose this log" -

# Output options
$ codex exec --json "Audit security"
$ codex exec -o last.txt "Summarize"

# Resume a previous exec session
$ codex exec resume --last "Fix the bugs"
$ codex exec resume <SESSION_ID> "Implement"

Global Options {.cols-2}

All Flags {.row-span-3}

{.show-header}

Usage Examples

# Specify model
$ codex -m gpt-5.4 "Refactor the auth module"

# Auto mode (low friction)
$ codex --full-auto "Run tests and fix failures"

# Attach a screenshot
$ codex -i mockup.png "Implement this UI"

# Override config inline
$ codex -c model="gpt-5.4-mini" "Quick scan"

# Live web search
$ codex --search "Find the latest async syntax"

# Set working directory
$ codex -C ~/projects/api "Review this codebase"

Sandbox & Approvals {.cols-3}

Sandbox Modes

Approval Policies

Presets {.primary}

Use /permissions in the TUI to change modes mid-session.

Slash Commands {.cols-3}

Session Control {.row-span-2}

Review & Code

Tools & Debug

Models {.cols-3}

Available Models {.col-span-2}

{.show-header}

Select a Model

$ codex -m gpt-5.4 "Your prompt"
$ codex -m gpt-5.4-mini "Quick task"
$ codex --oss    # local Ollama / LM Studio
# Mid-session: type /model in the TUI

Configuration {.cols-2}

config.toml Keys {.row-span-2}

# ~/.codex/config.toml

# Model settings
model = "gpt-5.4"
model_provider = "openai"
model_reasoning_effort = "medium"  # low | medium | high

# Sandbox & approvals
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# Web search: cached | live | disabled
web_search = "cached"

# Review model override
review_model = "gpt-5.4"

# TUI appearance
[tui]
theme = "dark"
alternate_screen = true

# Profile example
[profile.ci]
model = "gpt-5.4-mini"
approval_policy = "never"
sandbox_mode = "workspace-write"

Use -p ci to activate a profile.

Feature Flags

$ codex features list
$ codex features enable unified_exec
$ codex features disable shell_snapshot

# Per-session (not persisted)
$ codex --enable unified_exec
$ codex --disable shell_snapshot

Config Locations

Customization {.cols-3}

AGENTS.md {.row-span-2}

Persistent repo instructions, checked in alongside code:

## Build & test commands

- Install: `npm install`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions

- TypeScript strict mode
- No PII in logs
- Auth middleware on all routes

## Review guidelines

- Flag unhandled promise rejections

When to add rules:

• Repeated agent mistakes
• Recurring PR review feedback
• Tag @codex add to AGENTS.md in GitHub

Skills

Reusable workflows packaged as SKILL.md:

my-skill/
  SKILL.md      ← metadata + instructions
  scripts/      ← optional helper scripts
  references/   ← optional documentation
  assets/       ← optional templates

Example SKILL.md:

---
name: commit
description: Stage and commit changes
  in semantic groups.
---

1. Stage files in logical groups.
2. Group: feat → test → docs → chore
3. Write concise commit messages.

MCP Servers

# Add a stdio server
$ codex mcp add myserver -- npx my-mcp-server

# Add an HTTP server
$ codex mcp add myserver \
    --url https://api.example.com/mcp

# With auth token
$ codex mcp add myserver \
    --url https://api.example.com/mcp \
    --bearer-token-env-var MY_TOKEN

# List / remove
$ codex mcp list
$ codex mcp remove myserver

# Run Codex itself as MCP server
$ codex mcp-server

Session Management {.cols-3}

Resume Sessions

$ codex resume           # session picker
$ codex resume --last    # most recent session
$ codex resume --all     # across all directories
$ codex resume <ID> "Continue fixing tests"

Sessions stored at ~/.codex/sessions/

Fork a Session

$ codex fork             # fork from picker
$ codex fork --last      # fork most recent
$ codex fork <SESSION_ID> "New direction"

Forking preserves the original transcript while starting a new branch.

Image Inputs

# Single image
$ codex -i screenshot.png "Fix this error"

# Multiple images
$ codex --image img1.png,img2.jpg "Compare"

# Or drag images into the TUI composer

Supported: PNG, JPEG and other common formats.

Cloud & GitHub {.cols-3}

Cloud Tasks {.col-span-2}

# Browse cloud environments
$ codex cloud

# Submit a cloud task
$ codex cloud exec --env <ENV_ID> "Fix bug"

# With multiple attempts (best-of-N)
$ codex cloud exec --env <ENV_ID> \
    --attempts 3 "Write failing tests"

# List recent tasks
$ codex cloud list

# Check task status
$ codex cloud status <TASK_ID>

# Show diff for a task
$ codex cloud diff <TASK_ID>

# Apply diff to local working tree
$ codex apply <TASK_ID>

GitHub Integration

# In a PR comment – trigger code review:
@codex review

# Custom focus:
@codex review for security regressions

# Delegate any task using PR as context:
@codex fix the CI failures
@codex add tests for the new endpoint

Enable in Codex Settings → Code review → your repo. Turn on Automatic reviews to review every new PR.

Subagent Workflows {.cols-2}

Subagents Guide {.row-span-2}

Offload noisy work to parallel agents to avoid context pollution and context rot:

codex "Review this branch with parallel agents.
Spawn one for security risks, one for test gaps,
and one for maintainability. Wait for all three,
then summarize findings with file references."

• Use for: exploration, tests, triage, log analysis
• Avoid parallel write-heavy work (conflicts)
• Each subagent consumes extra tokens

Subagent model guide:

{.show-header}

Reasoning Effort

Set in config.toml:

model_reasoning_effort = "medium"

Or inline: -c model_reasoning_effort="high"

Also See {.cols-1}

• Official Codex Docs (developers.openai.com)
• Codex CLI GitHub (github.com)
• Codex Pricing (developers.openai.com)
• Customization Guide (developers.openai.com)
• Prompting Best Practices (developers.openai.com)
• Workflows & Examples (developers.openai.com)