Codex CLI Cheat Sheet

Printable single-page A4 JPEG reference for developers

Last updated: 09/05/2026

Concise reference for the Codex CLI: terminal UI, codex exec, local config, MCP, skills, subagents, hooks, rules, and automation.

I regularly write about agentic coding tools and workflows. If you want updates like these in your inbox, subscribe below. Thanks!

🚀 Start Here

Command	Use
`codex`	Open the interactive terminal UI in the current directory
`codex "prompt"`	Start an interactive session with an initial instruction
`codex exec "prompt"` / `codex e "prompt"`	Run Codex non-interactively for scripts or CI
`codex resume`	Pick and resume a previous interactive session
`codex resume --last`	Resume the latest session for this directory
`codex fork --last`	Fork the latest session into a new thread
`codex login`	Sign in with ChatGPT OAuth
`codex login --device-auth`	Sign in on remote/headless machines
`codex login --with-api-key`	Store API-key auth from stdin, e.g. pipe `OPENAI_API_KEY`
`codex login status`	Check auth; exits `0` when logged in
`codex logout`	Remove cached credentials
`codex update`	Check/apply a CLI update when supported
`codex completion <shell>`	Generate completions for `bash`, `zsh`, `fish`, `power-shell`, or `elvish`

🖥️ Interactive TUI

Input	Action
`@`	Fuzzy file search; insert a path into the prompt
`/command`	Run a slash command
`!cmd`	Run a local shell command under current approvals/sandbox
`Ctrl+C` or `/exit`	Exit the session
`Ctrl+L`	Clear/redraw screen without starting a new conversation
`Ctrl+O` or `/copy`	Copy latest completed Codex output
`Ctrl+R`	Search prompt history
`Ctrl+G`	Open prompt in `$VISUAL` or `$EDITOR`
`Tab` while Codex runs	Queue follow-up prompt, slash command, or `!` command
`Enter` while Codex runs	Inject instructions into the current turn
`Esc Esc` on empty composer	Edit previous user message; keep pressing `Esc` to go further back

⚡ Slash Commands

Use /help in the TUI for the exact command list in your installed version.

Command	Use
`/status`	Inspect current session state, workspace, and session id
`/permissions`	Switch approval/sandbox mode
`/clear`	Clear current conversation context
`/compact`	Summarize long context; Codex can also auto-compact
`/resume`	Resume a saved conversation from the TUI
`/fork`	Branch a new thread from the current transcript
`/side`	Start a side conversation
`/model`	Switch model and reasoning choices
`/fast on`, `/fast off`, `/fast status`	Toggle or inspect Fast mode
`/plan`	Enter Plan mode before implementation
`/review [focus]`	Run local code review presets
`/mcp`	Show active MCP servers
`/agent`	Switch/inspect active subagent threads
`/apps`	Use enabled ChatGPT app/connectors from the CLI
`/plugins`	Browse, install, uninstall, or toggle plugins
`/skills` or `$skill-name`	Browse or explicitly invoke skills
`/theme`	Preview/save syntax theme to `tui.theme`
`/mention`	Attach a specific file as context
`/experimental`	Toggle experimental features into config
`/personality`	Change supported-model communication style
`/feedback`	Send feedback, unless disabled by config

⚙️ Global Flags

Flag	Use
`--model <model>`, `-m`	Override configured model, e.g. `gpt-5.5` or `gpt-5.4`
`--profile <name>`, `-p`	Load `[profiles.<name>]` from `config.toml`
`--config key=value`, `-c key=value`	One-off config override; value is parsed as TOML
`--cd <path>`, `-C <path>`	Set workspace root before Codex starts
`--add-dir <path>`	Grant extra writable roots; repeatable
`--image <path[,path...]>`, `-i`	Attach image files to the first prompt
`--sandbox <mode>`, `-s`	`read-only`, `workspace-write`, or `danger-full-access`
`--ask-for-approval <mode>`, `-a`	`untrusted`, `on-request`, or `never`
`--search`	Use live web search instead of cached search
`--oss`	Use local OSS provider; requires Ollama or configured local provider
`--enable <feature>` / `--disable <feature>`	Force feature flag on/off for this run
`--no-alt-screen`	Disable alternate-screen TUI rendering
`--remote ws://host:port`	Connect TUI to a remote app server
`--remote-auth-token-env ENV`	Read remote WebSocket bearer token from env var
`--yolo`	Alias for `--dangerously-bypass-approvals-and-sandbox` ⚠️

🤖 `codex exec`

Command / Flag	Use
`codex exec "prompt"`	Run once; progress on `stderr`, final answer on `stdout`
`codex exec -`	Read the full prompt from stdin
`codex exec "instruction"` with piped stdin	Treat command output as extra context
`codex exec resume --last "prompt"`	Continue latest non-interactive session
`codex exec resume <SESSION_ID> "prompt"`	Resume a specific exec session
`--json`	Emit JSONL events: turns, items, tools, plans, errors
`--output-last-message <file>`, `-o <file>`	Save final assistant message
`--output-schema <file>`	Require final output matching JSON Schema
`--ephemeral`	Do not persist session rollout files
`--ignore-user-config`	Skip `$CODEX_HOME/config.toml`
`--ignore-rules`	Skip user/project `.rules` files
`--skip-git-repo-check`	Allow running outside a Git repo
`--color always`, `never`, or `auto`	Control ANSI color
`CODEX_API_KEY=... codex exec ...`	API-key auth for a single exec workflow

🔐 Approvals & Sandbox

Setting	Meaning
`--sandbox read-only`	Read files only; no edits or commands without approval
`--sandbox workspace-write`	Read/edit inside workspace and `--add-dir` roots
`--sandbox danger-full-access`	No filesystem sandbox; use only in isolated environments
`--ask-for-approval untrusted`	Prompt before untrusted commands
`--ask-for-approval on-request`	Prompt when Codex requests escalation
`--ask-for-approval never`	Never prompt; best for non-interactive, tightly sandboxed runs
`approvals_reviewer = "auto_review"`	Route eligible approvals through automatic review
`approval_policy = { granular = { ... } }`	Allow/deny categories such as sandbox, rules, MCP, skills
`default_permissions = ":workspace"`	Use built-in permission profile
`default_permissions = "custom"`	Use `[permissions.custom]` profile

Recommended default: codex --sandbox workspace-write --ask-for-approval on-request.

Protected in workspace-write mode: .git/, .codex/, and .agents/ are read-only when present. Use --add-dir or named permission profiles before reaching for full access.

🧩 Config Files & Keys

Path / Key	Use
`~/.codex/config.toml`	User config
`.codex/config.toml`	Project config; loaded only for trusted projects
`/etc/codex/config.toml`	Unix system config, if present
`CODEX_HOME`	Overrides `~/.codex` state/config root
`~/.codex/auth.json`	File credential cache; treat like a password
`~/.codex/history.jsonl`	Local history when enabled
`~/.codex/log/`	Local logs such as `codex-tui.log`
`requirements.toml`	Admin-enforced constraints

Precedence: CLI flags/-c > profile > project .codex/config.toml > user config > system config > defaults.

Common Key	Values / Use
`model`	Default model
`review_model`	Model override for `/review`
`model_provider`	Provider id, default `openai`
`openai_base_url`	Proxy/data-residency base URL for built-in OpenAI provider
`model_reasoning_effort`	`minimal`, `low`, `medium`, `high`, `xhigh`
`plan_mode_reasoning_effort`	Plan-mode-specific effort override
`model_reasoning_summary`	`auto`, `concise`, `detailed`, `none`
`model_verbosity`	`low`, `medium`, `high`
`personality`	`none`, `friendly`, `pragmatic`
`service_tier`	`flex` or `fast`
`web_search`	`cached`, `live`, or `disabled`
`project_root_markers`	Root detection markers, e.g. `[".git", ".hg"]`
`project_doc_max_bytes`	Max bytes read from `AGENTS.md` guidance
`project_doc_fallback_filenames`	Extra instruction filenames
`file_opener`	`vscode`, `cursor`, `windsurf`, `vscode-insiders`, `none`
`history.persistence`	`save-all` or `none`
`analytics.enabled`	Local analytics toggle
`feedback.enabled`	Enable `/feedback`
`cli_auth_credentials_store`	`file`, `keyring`, or `auto`

🧠 Models, Speed, Search

Feature	How
Recommended model	Use `gpt-5.5` when available; otherwise `gpt-5.4`
Switch model in TUI	`/model`
Set model for run	`codex --model gpt-5.5`
Fast mode	`/fast on`, `/fast off`, `/fast status`
Persist fast mode	`service_tier = "fast"` and `[features].fast_mode = true`
Codex-Spark	`gpt-5.3-codex-spark`, fast research-preview model for Pro users
Cached search	Default local web search mode
Live search	`--search` or `web_search = "live"`
Disable search	`web_search = "disabled"`

📁 `AGENTS.md` Guidance

Location	Purpose
`~/.codex/AGENTS.md`	Global personal guidance
`~/.codex/AGENTS.override.md`	Temporary global override
`<repo>/AGENTS.md`	Repo-level shared instructions
`<subdir>/AGENTS.override.md`	Local override for a subtree
`project_doc_fallback_filenames`	Treat other files as instruction files

Discovery order: global first, then project root down to current directory. In each directory Codex prefers AGENTS.override.md, then AGENTS.md, then fallback filenames. Later, closer files win.

Use /init to scaffold a starter AGENTS.md.

🔌 MCP

Command / Config	Use
`/mcp`	View active MCP servers in TUI
`codex mcp list [--json]`	List configured servers
`codex mcp get <name> [--json]`	Show one server
`codex mcp add <name> -- <command...>`	Add stdio server
`codex mcp add <name> --url https://...`	Add streamable HTTP server
`codex mcp remove <name>`	Remove server
`codex mcp login <name>`	OAuth login for supported HTTP servers
`codex mcp logout <name>`	Remove stored MCP OAuth credentials
`codex mcp-server`	Run Codex itself as an MCP server over stdio

`mcp_servers.<id>` Key	Use
`command`, `args`, `env`, `env_vars`, `cwd`	Stdio server launch
`url`, `bearer_token_env_var`	Streamable HTTP server
`http_headers`, `env_http_headers`	Static/env-backed HTTP headers
`enabled = false`	Disable without deleting
`required = true`	Fail startup/resume if server cannot initialize
`startup_timeout_sec`, `tool_timeout_sec`	Server/tool timeouts
`enabled_tools`, `disabled_tools`	Tool allow/deny lists
`mcp_oauth_callback_port`, `mcp_oauth_callback_url`	OAuth callback overrides

🛠️ Skills & Plugins

Surface	Use
`$skill-name`	Explicitly invoke a skill
`/skills`	Browse available skills
`$skill-creator`	Scaffold a new skill
`$skill-installer <name>`	Install curated/local skills
`[[skills.config]] path = ".../SKILL.md"; enabled = false`	Disable a skill
`/plugins`	Browse/install/uninstall/toggle plugins in CLI
`codex plugin marketplace add <source>`	Add plugin marketplace
`codex plugin marketplace upgrade [name]`	Refresh marketplace(s)
`codex plugin marketplace remove <name>`	Remove marketplace

Skill Location	Scope
`.agents/skills/<name>/SKILL.md`	Repo/team skill, searched from CWD up to repo root
`$HOME/.agents/skills/<name>/SKILL.md`	User skill
`/etc/codex/skills/<name>/SKILL.md`	Admin/system skill
Bundled skills	Built into Codex

SKILL.md requires name and description. Optional folders: scripts/, references/, assets/, and agents/openai.yaml. Package reusable skills as plugins when you want distribution plus optional apps/MCP config.

👥 Subagents

Concept	Use
Built-ins	`default`, `worker`, `explorer`
`/agent`	Switch between active agent threads
Explicit prompt	Codex only spawns subagents when you ask
`agents.max_threads`	Concurrent open agent cap; default `6`
`agents.max_depth`	Spawn nesting depth; default `1`
`agents.job_max_runtime_seconds`	Default timeout for CSV fan-out workers
`spawn_agents_on_csv`	Experimental batch fan-out from CSV

Custom agents live in ~/.codex/agents/*.toml or .codex/agents/*.toml and require:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = "Review code like an owner. Lead with real risks."

Optional custom-agent keys include nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. Subagents inherit the parent sandbox/runtime overrides unless the workflow explicitly changes them.

🧱 Rules & Hooks

Rules	Use
`~/.codex/rules/default.rules`	User command rules
`<repo>/.codex/rules/*.rules`	Project rules; trusted projects only
`codex execpolicy check --pretty --rules file -- cmd ...`	Test rule decisions
`prefix_rule(pattern=[...], decision="allow")`	Allow matching command prefix
`decision = "prompt"`	Ask before matching command
`decision = "forbidden"`	Block matching command

Rules apply when Codex requests commands outside the sandbox. Decisions combine as forbidden > prompt > allow.

Hooks	Use
`[features].codex_hooks = true`	Enable lifecycle hooks
`~/.codex/hooks.json` / `~/.codex/config.toml`	User hooks
`<repo>/.codex/hooks.json` / `.codex/config.toml`	Project hooks; trusted projects only
`SessionStart`	Add context at startup/resume/clear
`PreToolUse`	Inspect/block supported Bash, patch, or MCP calls before use
`PermissionRequest`	Allow/deny approval requests
`PostToolUse`	Inspect tool output and feed feedback back to Codex
`UserPromptSubmit`	Add context or block a prompt
`Stop`	Continue or stop after a turn completes

Hook commands receive JSON on stdin. matcher is regex-based; common matchers include Bash, apply_patch, Edit|Write, and mcp__server__tool.

🧪 Feature Flags & TUI Tweaks

Command / Key	Use
`codex features list`	Show feature flags and effective state
`codex features enable <feature>`	Persistently enable in `config.toml`
`codex features disable <feature>`	Persistently disable in `config.toml`
`[features].unified_exec`	PTY-backed exec tool; default on except Windows
`[features].shell_snapshot`	Snapshot shell env for faster commands
`[features].multi_agent`	Enable subagent tools
`[features].memories`	Enable memories
`[features].codex_hooks`	Enable hooks
`[features].remote_connections`	Enable alpha SSH remote connections
`tui.theme`	Saved syntax theme
`tui.alternate_screen = "never"`	Preserve terminal scrollback
`tui.notifications`	Enable/filter TUI notifications
`tui.keymap.<context>.<action>`	Customize key bindings

🧰 Providers, Auth, Environment

Config / Env	Use
`model_provider = "openai"`	Built-in OpenAI provider
`openai_base_url = "https://..."`	Built-in OpenAI provider base URL override
`[model_providers.<id>]`	Custom provider definition
`env_key = "PROVIDER_API_KEY"`	Provider API key env var
`[model_providers.<id>.auth]`	Command-backed bearer token
`model_provider = "amazon-bedrock"`	Built-in Bedrock provider
`oss_provider = "ollama"` / `"lmstudio"`	Default provider for `--oss`
`[shell_environment_policy]`	Control env vars passed to subprocesses
`CODEX_CA_CERTIFICATE`	Custom CA bundle; falls back to `SSL_CERT_FILE`
`forced_login_method = "chatgpt"` / `"api"`	Restrict auth method
`forced_chatgpt_workspace_id = "uuid"`	Restrict ChatGPT workspace

🧵 Sessions, Remote TUI, Cloud

Task	Command
Resume picker	`codex resume`
Resume latest	`codex resume --last`
Resume by ID	`codex resume <SESSION_ID>`
Include all dirs	`codex resume --all`
Fork picker	`codex fork`
Start app server	`codex app-server --listen ws://127.0.0.1:4500`
Connect TUI	`codex --remote ws://127.0.0.1:4500`
Secure app server	`--ws-auth capability-token --ws-token-file /abs/token`
Remote bearer env	`codex --remote wss://host:4500 --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN`
Browse cloud tasks	`codex cloud`
Submit cloud task	`codex cloud exec --env ENV_ID "prompt"`
Best-of-N cloud task	`codex cloud exec --env ENV_ID --attempts 3 "prompt"`
List cloud tasks	`codex cloud list --env ENV_ID --limit 20 --json`
Apply cloud diff	`codex apply <TASK_ID>`

Use SSH port forwarding or TLS plus auth for non-local app-server access. Do not expose unauthenticated WebSocket listeners on shared/public networks.

✅ Workflow Patterns

Goal	Prompt / Command Pattern
Explain code	`Read @file1 @file2 and explain the request flow, data validation, and gotchas.`
Fix a bug	Provide repro steps, constraints, suspected files, and "done when" checks
Add tests	`Add tests for <function> in @file; cover happy path and edge cases.`
Prototype from image	`codex -i screenshot.png "Build this UI; constraints: ..."`
Review locally	`/review` or `/review Focus on security and edge cases`
CI summary	Pipe logs into `codex exec "Summarize failures and likely fixes"`
Structured CI output	`codex exec --json --output-schema schema.json -o result.json "..."`
Large parallel review	Ask Codex to spawn one subagent per review area and consolidate findings

Prompt template: Goal + Context + Constraints + Done when. Move durable guidance into AGENTS.md, repeatable methods into skills, external live context into MCP, and stable automation into codex exec or cloud tasks.