Codex CLI cheatsheet

#Getting Started

Install & Run

npm (recommended)

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

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.

Programming

Shell completions

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

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

Command Reference

Command	Alias	Status	Description
`codex`		Stable	Launch interactive TUI
`codex exec`	`codex e`	Stable	Run non-interactively (scripting)
`codex review`		Stable	Non-interactive code review
`codex resume`		Stable	Resume a previous session
`codex fork`		Stable	Fork a session into new thread
`codex apply`	`codex a`	Stable	Apply Cloud task diff locally
`codex login`		Stable	Authenticate Codex
`codex logout`		Stable	Remove stored credentials
`codex completion`		Stable	Generate shell completions
`codex features`		Stable	Manage feature flags
`codex app`		Stable	Launch Codex desktop app
`codex mcp`		Experimental	Manage MCP servers
`codex mcp-server`		Experimental	Run Codex as an MCP server
`codex cloud`		Experimental	Browse and exec Cloud tasks
`codex sandbox`		Experimental	Run cmds inside sandbox
`codex debug`		Experimental	Debugging tools

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

All Flags

Flag	Values	Description
`-m, --model`	string	Model override (e.g. `gpt-5.4`)
`-s, --sandbox`	see below	Sandbox policy
`-a, --ask-for-approval`	see below	Approval policy
`--full-auto`	flag	workspace-write + on-request
`--yolo`	flag	Bypass all approvals/sandbox
`-i, --image`	path	Attach image(s) to initial prompt
`-c, --config`	`key=val`	Override a config value
`-C, --cd`	path	Agent working directory
`-p, --profile`	string	Config profile name
`--search`	flag	Enable live web search
`--add-dir`	path	Grant extra directory write access
`--oss`	flag	Use local OSS provider
`--local-provider`	lmstudio/ollama	Specify OSS provider
`--enable`	feature	Enable a feature flag
`--disable`	feature	Disable a feature flag
`--no-alt-screen`	flag	Inline TUI mode (no alt screen)
`--remote`	ws://host:port	Connect to remote app server
`--remote-auth-token-env`	ENV_VAR	Bearer token env var for remote WS
`-V, --version`		Print version
`-h, --help`		Print help

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

Sandbox Modes

`read-only`	Inspect only, no edits without approval
`workspace-write`	Edit workspace + run local commands
`danger-full-access`	No restrictions (use in hardened envs)

Approval Policies

`untrusted`	Ask before all non-trusted commands
`on-request`	Ask when going beyond sandbox boundary
`never`	Never ask; all commands run automatically

Presets

`--full-auto`	`workspace-write` + `on-request`
`--yolo`	No sandbox + No approvals

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

#Slash Commands

Session Control

`/model`	Switch model / reasoning effort
`/fast`	Toggle GPT-5.4 Fast mode
`/permissions`	Adjust approval mode
`/personality`	Set response style
`/plan`	Enter planning mode
`/status`	Show model, tokens, config
`/compact`	Summarize to free context
`/clear`	Clear chat + start fresh
`/new`	New chat, keep CLI session
`/fork`	Fork current conversation
`/resume`	Resume saved session
`/exit` / `/quit`	Exit the CLI

Review & Code

`/review`	Launch code reviewer
`/diff`	Show Git diff
`/copy`	Copy latest Codex output
`/mention`	Attach file to conversation
`/init`	Generate AGENTS.md scaffold

Tools & Debug

`/agent`	Switch active agent thread
`/mcp`	List MCP tools
`/apps`	Browse connector apps
`/experimental`	Toggle experimental features
`/statusline`	Configure TUI footer
`/ps`	Show background terminals
`/sandbox-add-read-dir`	Add readable dir (Windows)
`/feedback`	Send logs to maintainers
`/plugins`	Browse and manage plugins
`/title`	Set terminal title for session
`/debug-config`	Print config diagnostics
`/logout`	Sign out of Codex

#Models

Available Models

Model	Speed	Best for
`gpt-5.4`	★★★	Default – coding + reasoning + workflows
`gpt-5.4-mini`	★★★★★	Subagents, light tasks, higher limits
`gpt-5.3-codex`	★★★★	Complex software engineering
`gpt-5.3-codex-spark`	★★★★★	Near-instant iteration (Pro only)

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

config.toml Keys

# ~/.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

`~/.codex/config.toml`	Global defaults
`~/.codex/AGENTS.md`	Personal instructions
`~/.agents/skills/`	Personal skills
`.agents/skills/`	Repo-level skills
`AGENTS.md`	Repo instructions

#Customization

AGENTS.md

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

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

When to add rules:

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

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

Cloud Tasks

# 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

Subagents Guide

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:

Role	Model	Reasoning
Main coordinator	`gpt-5.4`	medium
Fast exploration	`gpt-5.4-mini`	low
Security / logic review	`gpt-5.4`	high

Reasoning Effort

`high`	Complex logic, security audits
`medium`	General tasks (default)
`low`	Simple or speed-critical tasks

Set in config.toml:

model_reasoning_effort = "medium"

Or inline: -c model_reasoning_effort="high"

#Also See

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)