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.
🚀 Start Here
Command | Use |
|---|---|
| Open the interactive terminal UI in the current directory |
| Start an interactive session with an initial instruction |
| Run Codex non-interactively for scripts or CI |
| Pick and resume a previous interactive session |
| Resume the latest session for this directory |
| Fork the latest session into a new thread |
| Sign in with ChatGPT OAuth |
| Sign in on remote/headless machines |
| Store API-key auth from stdin, e.g. pipe |
| Check auth; exits |
| Remove cached credentials |
| Check/apply a CLI update when supported |
| Generate completions for |
🖥️ Interactive TUI
Input | Action |
|---|---|
| Fuzzy file search; insert a path into the prompt |
| Run a slash command |
| Run a local shell command under current approvals/sandbox |
| Exit the session |
| Clear/redraw screen without starting a new conversation |
| Copy latest completed Codex output |
| Search prompt history |
| Open prompt in |
| Queue follow-up prompt, slash command, or |
| Inject instructions into the current turn |
| Edit previous user message; keep pressing |
⚡ Slash Commands
Use /help in the TUI for the exact command list in your installed version.
Command | Use |
|---|---|
| Inspect current session state, workspace, and session id |
| Switch approval/sandbox mode |
| Clear current conversation context |
| Summarize long context; Codex can also auto-compact |
| Resume a saved conversation from the TUI |
| Branch a new thread from the current transcript |
| Start a side conversation |
| Switch model and reasoning choices |
| Toggle or inspect Fast mode |
| Enter Plan mode before implementation |
| Run local code review presets |
| Show active MCP servers |
| Switch/inspect active subagent threads |
| Use enabled ChatGPT app/connectors from the CLI |
| Browse, install, uninstall, or toggle plugins |
| Browse or explicitly invoke skills |
| Preview/save syntax theme to |
| Attach a specific file as context |
| Toggle experimental features into config |
| Change supported-model communication style |
| Send feedback, unless disabled by config |
⚙️ Global Flags
Flag | Use |
|---|---|
| Override configured model, e.g. |
| Load |
| One-off config override; value is parsed as TOML |
| Set workspace root before Codex starts |
| Grant extra writable roots; repeatable |
| Attach image files to the first prompt |
|
|
|
|
| Use live web search instead of cached search |
| Use local OSS provider; requires Ollama or configured local provider |
| Force feature flag on/off for this run |
| Disable alternate-screen TUI rendering |
| Connect TUI to a remote app server |
| Read remote WebSocket bearer token from env var |
| Alias for |
🤖 codex exec
Command / Flag | Use |
|---|---|
| Run once; progress on |
| Read the full prompt from stdin |
| Treat command output as extra context |
| Continue latest non-interactive session |
| Resume a specific exec session |
| Emit JSONL events: turns, items, tools, plans, errors |
| Save final assistant message |
| Require final output matching JSON Schema |
| Do not persist session rollout files |
| Skip |
| Skip user/project |
| Allow running outside a Git repo |
| Control ANSI color |
| API-key auth for a single exec workflow |
🔐 Approvals & Sandbox
Setting | Meaning |
|---|---|
| Read files only; no edits or commands without approval |
| Read/edit inside workspace and |
| No filesystem sandbox; use only in isolated environments |
| Prompt before untrusted commands |
| Prompt when Codex requests escalation |
| Never prompt; best for non-interactive, tightly sandboxed runs |
| Route eligible approvals through automatic review |
| Allow/deny categories such as sandbox, rules, MCP, skills |
| Use built-in permission profile |
| Use |
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 |
|---|---|
| User config |
| Project config; loaded only for trusted projects |
| Unix system config, if present |
| Overrides |
| File credential cache; treat like a password |
| Local history when enabled |
| Local logs such as |
| Admin-enforced constraints |
Precedence: CLI flags/-c > profile > project .codex/config.toml > user config > system config > defaults.
Common Key | Values / Use |
|---|---|
| Default model |
| Model override for |
| Provider id, default |
| Proxy/data-residency base URL for built-in OpenAI provider |
|
|
| Plan-mode-specific effort override |
|
|
|
|
|
|
|
|
|
|
| Root detection markers, e.g. |
| Max bytes read from |
| Extra instruction filenames |
|
|
|
|
| Local analytics toggle |
| Enable |
|
|
🧠 Models, Speed, Search
Feature | How |
|---|---|
Recommended model | Use |
Switch model in TUI |
|
Set model for run |
|
Fast mode |
|
Persist fast mode |
|
Codex-Spark |
|
Cached search | Default local web search mode |
Live search |
|
Disable search |
|
📁 AGENTS.md Guidance
Location | Purpose |
|---|---|
| Global personal guidance |
| Temporary global override |
| Repo-level shared instructions |
| Local override for a subtree |
| 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 |
|---|---|
| View active MCP servers in TUI |
| List configured servers |
| Show one server |
| Add stdio server |
| Add streamable HTTP server |
| Remove server |
| OAuth login for supported HTTP servers |
| Remove stored MCP OAuth credentials |
| Run Codex itself as an MCP server over stdio |
| Use |
|---|---|
| Stdio server launch |
| Streamable HTTP server |
| Static/env-backed HTTP headers |
| Disable without deleting |
| Fail startup/resume if server cannot initialize |
| Server/tool timeouts |
| Tool allow/deny lists |
| OAuth callback overrides |
🛠️ Skills & Plugins
Surface | Use |
|---|---|
| Explicitly invoke a skill |
| Browse available skills |
| Scaffold a new skill |
| Install curated/local skills |
| Disable a skill |
| Browse/install/uninstall/toggle plugins in CLI |
| Add plugin marketplace |
| Refresh marketplace(s) |
| Remove marketplace |
Skill Location | Scope |
|---|---|
| Repo/team skill, searched from CWD up to repo root |
| User skill |
| 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 |
|
| Switch between active agent threads |
Explicit prompt | Codex only spawns subagents when you ask |
| Concurrent open agent cap; default |
| Spawn nesting depth; default |
| Default timeout for CSV fan-out workers |
| 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 |
|---|---|
| User command rules |
| Project rules; trusted projects only |
| Test rule decisions |
| Allow matching command prefix |
| Ask before matching command |
| Block matching command |
Rules apply when Codex requests commands outside the sandbox. Decisions combine as forbidden > prompt > allow.
Hooks | Use |
|---|---|
| Enable lifecycle hooks |
| User hooks |
| Project hooks; trusted projects only |
| Add context at startup/resume/clear |
| Inspect/block supported Bash, patch, or MCP calls before use |
| Allow/deny approval requests |
| Inspect tool output and feed feedback back to Codex |
| Add context or block a prompt |
| 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 |
|---|---|
| Show feature flags and effective state |
| Persistently enable in |
| Persistently disable in |
| PTY-backed exec tool; default on except Windows |
| Snapshot shell env for faster commands |
| Enable subagent tools |
| Enable memories |
| Enable hooks |
| Enable alpha SSH remote connections |
| Saved syntax theme |
| Preserve terminal scrollback |
| Enable/filter TUI notifications |
| Customize key bindings |
🧰 Providers, Auth, Environment
Config / Env | Use |
|---|---|
| Built-in OpenAI provider |
| Built-in OpenAI provider base URL override |
| Custom provider definition |
| Provider API key env var |
| Command-backed bearer token |
| Built-in Bedrock provider |
| Default provider for |
| Control env vars passed to subprocesses |
| Custom CA bundle; falls back to |
| Restrict auth method |
| Restrict ChatGPT workspace |
🧵 Sessions, Remote TUI, Cloud
Task | Command |
|---|---|
Resume picker |
|
Resume latest |
|
Resume by ID |
|
Include all dirs |
|
Fork picker |
|
Start app server |
|
Connect TUI |
|
Secure app server |
|
Remote bearer env |
|
Browse cloud tasks |
|
Submit cloud task |
|
Best-of-N cloud task |
|
List cloud tasks |
|
Apply cloud diff |
|
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 |
|
Fix a bug | Provide repro steps, constraints, suspected files, and "done when" checks |
Add tests |
|
Prototype from image |
|
Review locally |
|
CI summary | Pipe logs into |
Structured CI output |
|
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.
