Codex cheatsheet

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # macOS/Linux
npm install -g @openai/codex                           # npm
brew install --cask codex                              # macOS

On Windows, run irm https://chatgpt.com/codex/install.ps1 | iex in PowerShell. See: Getting started

codex                 # first run opens a browser login
codex login           # sign in again
codex login status    # show the current account

Codex works with a ChatGPT plan or an API key. For scripts, pipe a key in: printenv OPENAI_API_KEY | codex login --with-api-key. See: Authentication

codex                      # start the interactive TUI
codex "explain this repo"  # start with a prompt
codex resume --last        # reopen the latest chat
codex fork --last          # branch the latest chat

codex resume scopes --last to the current directory; add --all to search every session. See: CLI reference

Sessions

Command	Description
codex	Start the interactive TUI
codex resume	Reopen a saved chat
codex fork	Branch a saved chat into a new one
codex archive <chat>	Hide a chat from the picker
codex delete <chat>	Delete a chat and its transcript

Setup

Command	Description
codex login	Sign in with ChatGPT
codex logout	Remove stored credentials
codex update	Update to the latest version
codex doctor	Diagnose install and config
codex completion zsh	Generate shell completions
codex mcp	Manage MCP servers
codex plugin	Install and remove plugins

Automation

Command	Description
codex exec "task"	Run non-interactively
codex review	Review changes non-interactively
codex cloud	Browse and run cloud chats
codex apply <task>	Apply a cloud diff locally

Flag	Description
-m, --model <model>	Choose the model
-p, --profile <name>	Layer a profile over config
-s, --sandbox <mode>	Set the sandbox policy
-a, --ask-for-approval <policy>	Control approval prompts
-C, --cd <dir>	Set the working directory
--add-dir <dir>	Grant another writable folder
--search	Enable live web search
-i, --image <file>	Attach images to the prompt
-c key=value	Override any config value

Other flags

Flag	Description
--oss	Use a local open-source model
--no-alt-screen	Keep output in terminal scrollback
--enable <feature>	Enable optional features
--dangerously-bypass-approvals-and-sandbox	Skip approvals and sandboxing

codex exec "summarize this repo"        # final message to stdout
git diff | codex exec "review this"     # pipe context in
codex exec --json "list failing tests"  # JSONL events
codex exec resume --last "fix them"     # continue the last run

codex exec runs read-only by default; add --sandbox workspace-write to allow edits. -o file writes the final message to a file. See: Non-interactive mode

codex review --uncommitted   # staged, unstaged, and untracked
codex review --base main     # changes against a base branch
codex review --commit <sha>  # a single commit

Pass exactly one target, or give custom instructions as a prompt. --title only works with --commit. See: Code review

Chat

Command	Description
/new	Start a fresh chat
/clear	Clear the terminal and start fresh
/resume	Reopen a saved chat
/fork	Branch the current chat
/compact	Summarize to free up context
/rename <name>	Rename the current chat

Control

Command	Description
/plan	Switch to plan mode
/goal <objective>	Set a persistent task goal
/permissions	Change what Codex may do
/approve	Retry an auto-denied action
/model	Choose the active model
/fast	Toggle the Fast service tier

Inspect

Command	Description
/diff	Show the Git diff
/review	Review the working tree
/status	Show model, policy, and tokens
/usage	Show account token usage
/copy	Copy the latest response

Config

Command	Description
/init	Generate an AGENTS.md scaffold
/skills	Browse and apply skills
/plugins	Browse installed plugins
/mcp	List configured MCP tools
/hooks	Manage lifecycle hooks

Interface

Command	Description
/theme	Choose a syntax theme
/statusline	Configure footer items
/vim	Toggle Vim composer mode
/keymap	Remap TUI shortcuts

Account

Command	Description
/import	Import Claude Code or Cursor setup
/feedback	Send logs to the maintainers
/logout	Sign out
/quit	Exit the CLI (also /exit)

Session

Shortcut	Description
Ctrl+C	Close the session
Ctrl+R	Search prompt history
Ctrl+O	Copy the latest response
Ctrl+L	Clear the terminal view
Ctrl+G	Edit the prompt in $VISUAL/$EDITOR
Esc Esc	Edit the previous message and fork
Alt+R	Toggle raw scrollback
Up Down	Restore draft history

While running

Shortcut	Description
Enter	Inject instructions into the turn
Tab	Queue a follow-up for the next turn

Input	Effect
/	Slash commands
@	Search files and add paths
!	Run a shell command directly

Paste an image into the composer. See: Image inputs

~/.codex/config.toml            # user settings
.codex/config.toml              # project settings (trusted projects)
$CODEX_HOME/<name>.config.toml  # profile, selected with --profile
/etc/codex/config.toml          # system defaults (Unix)

model = "gpt-6.1-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"

Project files merge from the repo root down to the current directory; CLI flags and -c key=value overrides win. See: Config basics

Variable	Purpose
CODEX_HOME	State directory (default ~/.codex)
CODEX_API_KEY	API key for non-interactive runs
CODEX_ACCESS_TOKEN	Access token for trusted automation
CODEX_CA_CERTIFICATE	PEM CA bundle for corporate TLS
RUST_LOG	Log verbosity for debugging

AGENTS.md            # project instructions, committed
~/.codex/AGENTS.md   # global defaults for every repo

Each directory contributes one file — AGENTS.override.md if present, else AGENTS.md — and Codex concatenates them from the repo root down. See: AGENTS.md

# Machine-readable events for scripts
codex exec --json "list the failing tests" | jq

# Capture the final message in a file
codex exec -o summary.md "summarize this repo"

# Use an API key inline in CI
CODEX_API_KEY=$KEY codex exec "triage open bugs"

codex review --uncommitted
codex review --base main
git diff | codex exec "review this diff for bugs"

Inside a session, /review reviews the working tree and /diff shows the changes.

codex cloud list                # recent cloud chats
codex cloud exec --env <id> "fix the flaky test"
codex apply <task-id>           # apply the diff locally

codex cloud exec needs --env; add --attempts 2 for best-of-N. See: Codex Cloud

codex mcp add my-server -- npx my-mcp-server        # stdio
codex mcp add remote --url https://example.com/mcp  # HTTP
codex mcp list

Add --env KEY=VALUE for stdio servers, or --bearer-token-env-var VAR for HTTP.

codex mcp login my-server             # OAuth, opens a browser
codex mcp login my-server --scopes read:docs
codex mcp logout my-server

OAuth works with streamable HTTP servers that support it. Stored credentials live in the store set by mcp_oauth_credentials_store (auto, file, or keyring). See: MCP