OpenAI Codex CLI is OpenAI's terminal-native coding agent that inspects codebases, edits files, runs tests, integrates with Codex Cloud remote tasks, and connects to external tools via MCP directly from your command line.
This cheat sheet covers Codex CLI subcommands and flags, sandbox and approval policies, interactive TUI slash commands, keyboard shortcuts, and config.toml / AGENTS.md configuration.
🔗 Related Cheat Sheets: Terminal AI Coding CLIs Comparison Cheat Sheet · Claude Code CLI Cheat Sheet · Antigravity CLI (agy) Cheat Sheet · AI Agent Harness Engineering Cheat Sheet
1. Installation, Authentication & Core CLI Commands
1.1 Installation & Authentication
| Action | Command | Notes |
|---|---|---|
| Global npm install | npm install -g @openai/codex |
Standard cross-platform installation |
| Official install script | curl -fsSL https://chatgpt.com/codex/install.sh | sh |
One-line installer for macOS / Linux |
| Browser login | codex login |
Authenticate with ChatGPT Plus / Pro / Team account |
| API key auth | export OPENAI_API_KEY="sk-..." |
Ideal for headless CI or container environments |
1.2 CLI Subcommands & Global Flags
| Command / Flag | Description | Example Usage |
|---|---|---|
codex |
Launch the interactive TUI in the current directory | codex |
codex "prompt" |
Start an interactive session with an initial prompt | codex "Debug 500 timeout errors on login" |
codex exec / codex e |
Non-interactive (headless) execution for scripts and CI | codex exec "Run all unit tests and fix failures" |
codex exec --json |
Stream structured JSON logs of reasoning and file edits | codex exec --json "Refactor utils" > run.jsonl |
codex review |
Non-interactive code review on current Git diff | codex review |
codex resume |
Open session picker (stored in ~/.codex/sessions/) |
codex resume / codex resume --last / codex resume <id> |
codex apply / codex a |
Apply diffs generated by Codex Cloud tasks to local workspace | codex apply <task_id> |
codex cloud |
Inspect or manage remote Codex Cloud tasks | codex cloud |
codex mcp |
Manage Model Context Protocol (MCP) server integrations | codex mcp list / codex mcp add <name> ... |
-m, --model <name> |
Specify the underlying model for the session or run | codex -m gpt-6.1-sol |
--strict-config |
Strictly validate config.toml syntax and keys |
codex --strict-config |
2. Sandbox & Approval Policy Matrix
Codex CLI separates permissions into two orthogonal layers: what the environment can touch (--sandbox) and when to ask the user (--ask-for-approval).
| Flag | Valid Values | Behavior & Recommended Usage |
|---|---|---|
--sandbox <mode>(alias -s) |
read-only |
Read-only: inspect and search code without modifying files |
workspace-write |
Workspace write (Recommended default): allow edits only within the working tree | |
danger-full-access |
Unrestricted access: full filesystem/system access (isolated containers only) | |
--ask-for-approval <policy> |
on-request |
Recommended default: model prompts for confirmation when risky actions require it |
on-failure |
Escalate only on failure (use on-request if sandbox elevation prompts matter) |
|
never |
Fully silent: never prompt interactively (for CI / automated pipelines) |
⚠️ Deprecated & Retired Flags Notice:
--full-autois deprecated as ofv0.128.0. Specify sandbox and approval policies explicitly:codex --sandbox workspace-write --ask-for-approval on-request "Fix failing tests"- The
untrustedapproval policy was retired inv0.149.0; migrate configurations toon-request.
3. Interactive TUI Slash Commands
Type / inside the interactive codex TUI prompt to control context, permissions, and workflows:
3.1 Context, Models & Permissions
| Command | Function | Notes & Usage |
|---|---|---|
/init |
Generate a starter AGENTS.md tailored to the repository |
Recommended first step in a new project |
/status |
Inspect active model, permissions, and token usage | Monitor remaining context capacity |
/model |
Interactively switch model and Reasoning Effort tier | Tune reasoning depth without restarting |
/permissions |
Adjust sandbox mode and approval policy mid-session | Tighten or relax permissions on demand |
/mcp |
Inspect and manage connected MCP servers | Verify external tool and DB connectivity |
3.2 Engineering Workflows & Session Control
| Command | Function | Notes & Usage |
|---|---|---|
/plan |
Draft and review an implementation plan before editing files | Align on architecture prior to large refactors |
/review |
Run multi-perspective code review on uncommitted changes | Catch bugs, edge cases, and security risks |
/diff |
Inspect current uncommitted file modifications | Review line-by-line diffs before accepting |
/fork |
Branch the conversation thread into a separate checkpoint | Explore an alternative approach without polluting main context |
/compact |
Summarize conversation history to reclaim context headroom | Prevent drift in long multi-turn sessions |
/copy |
Copy the latest completed response to clipboard | Quickly extract patches or summaries |
/title |
Rename the current conversation thread | Makes sessions easy to find in codex resume |
/statusline / /theme |
Customize footer status items or TUI color theme | Tailor terminal presentation |
/prompts:<name> |
Invoke a custom Markdown prompt template | Executes ~/.codex/prompts/<name>.md |
4. Terminal Keybindings & Input Syntax
| Shortcut / Syntax | Action | Effect & Scenario |
|---|---|---|
@<path> |
Fuzzy file reference | Inject file contents inline (e.g., @src/auth.ts) |
!<command> |
Inline local shell command | Run shell commands within active sandbox rules (e.g., !npm test) |
Tab |
Queue next prompt | Queue a follow-up prompt, slash command, or ! command while Codex works |
Enter |
Interrupt / steer mid-run | Inject additional guidance while the agent is actively responding |
Ctrl + G |
Open external editor | Draft multiline prompts in $VISUAL / $EDITOR (Vim, VS Code, etc.) |
Ctrl + R |
Search prompt history | Reverse-search previously submitted prompts |
Ctrl + L |
Clear & redraw screen | Clear terminal clutter while preserving conversation state |
Ctrl + O |
Copy latest output | Equivalent to /copy |
Ctrl + X |
Open keyboard menu | Access keyboard presets and extensions |
Ctrl + C |
Cancel / Exit | Abort active task or exit the Codex session |
5. Configuration Files & Memory Hierarchy (config.toml & AGENTS.md)
Project-level settings override global user defaults:
| Layer | Global Scope (All Repos) | Project Scope (Current Repo) | Purpose |
|---|---|---|---|
| Core config | ~/.codex/config.toml |
.codex/config.toml |
Default model, sandbox, approval policy, network toggle, MCP |
| Agent instructions | ~/.codex/AGENTS.md |
./AGENTS.md (repo root) |
Build/test commands, coding standards, architecture rules |
| Custom prompts | ~/.codex/prompts/*.md |
— | Reusable /prompts:<name> slash command templates |
| Session logs | ~/.codex/sessions/ |
— | Persistent logs restored by codex resume |
Minimal Recommended ~/.codex/config.toml
# Default model
model = "gpt-6.1-sol"
# Default sandbox and approval policy
sandbox_mode = "workspace-write"
approval_policy = "on-request"
# Restrict outbound network access inside sandbox by default
network_access = false