You installed Codex, typed codex into your terminal, and wondered: "Okay, now what?"
Same here. OpenAI's coding agent ships with dozens of CLI commands, more than 40 slash commands in the interactive TUI, and a separate desktop app with its own shortcuts. Without a reference, you lose track fast.
This article lays out every Codex command in one place. Each CLI command, every slash command, all flags, every keyboard shortcut for CLI and App. It's the most thorough Codex reference you'll find in English. If you'd rather compare Codex head-to-head with Claude Code, our in-depth Claude Code vs. OpenAI Codex comparison has you covered.
TL;DRKey Takeaways
- 30+ CLI commands cover the whole tool, from codex exec (non-interactive execution) to codex review (code review) and codex cloud (cloud tasks)
- Over 40 slash commands in the composer control the model, permissions, sessions, plan mode, and more, with parameter and (where documented) introduction-version columns
- Three sandbox modes (read-only, workspace-write, danger-full-access) and four approval policies control what Codex can do on your system
- Codex Cloud offloads long-running tasks to remote sandboxed environments, with best-of-N attempts on demand
Installing and Starting Codex
Codex CLI installs via npm or Homebrew. On first launch, Codex asks you to sign in with your ChatGPT account or an API key.
# Install via npm
npm install -g @openai/codex
# Or via Homebrew (native Rust binary, faster)
brew install codex# Sign in interactively (opens browser for OAuth)
codex login
# Sign in with an API key
echo $OPENAI_API_KEY | codex login --with-api-key
# Check login status
codex login status
# Sign out
codex logout# Start an interactive TUI session
codex
# Start with an initial prompt
codex "Explain the architecture of this project"
# Run non-interactively (for scripts)
codex exec -s workspace-write -m gpt-5.5 "Refactor auth.ts"
# Launch the desktop app
codex appTip
Always start Codex inside the right project folder. You can also set the working directory explicitly with
--cd /path/to/project.CLI Commands (Overview)
Codex comes in two flavors. The CLI runs in your terminal. The App is a desktop application for macOS and Windows. The "Example" column shows the typical usage of each command.
Command | Description | Example |
|---|---|---|
codex | Start an interactive TUI session in the terminal | codex |
codex app | Launch the Codex desktop app (macOS/Windows) | codex app |
codex exec | Run a task non-interactively, stream output to stdout | codex exec "Fix bug" |
codex exec resume | Resume a previous session non-interactively | codex exec resume --last "Continue task" |
codex review | Code review (uncommitted, branch diff, or commit) | codex review --uncommitted |
codex apply | Apply a diff from a Codex session or cloud task | codex apply TASK_ID |
codex resume | Resume an interactive session (session picker) | codex resume |
codex fork | Fork a session into a new thread | codex fork |
codex cloud exec | Submit a cloud task in a sandbox environment | codex cloud exec --env ENV_ID "..." |
codex cloud list | List cloud tasks (with filter and pagination) | codex cloud list |
codex cloud status | Show the status of a cloud task | codex cloud status ID |
codex cloud diff | Show the diff of a cloud task | codex cloud diff ID |
codex cloud apply | Apply a cloud task diff locally | codex cloud apply ID |
codex mcp add | Add an MCP server (stdio or HTTP) | codex mcp add name -- cmd |
codex mcp list | List configured MCP servers | codex mcp list |
codex mcp get | Show an MCP server's configuration | codex mcp get name |
codex mcp remove | Remove an MCP server | codex mcp remove name |
codex mcp login | OAuth login for an MCP server | codex mcp login name |
codex mcp logout | Remove an MCP server's OAuth credentials | codex mcp logout name |
codex features list | Show feature flags with status and maturity | codex features list |
codex features enable/disable | Enable or disable a feature flag persistently | codex features enable NAME |
codex login | Sign in via OAuth or API key | codex login |
codex login status | Show the current login status | codex login status |
codex logout | Remove stored credentials | codex logout |
codex sandbox | Run a command in the Codex sandbox (macOS/Linux/Windows) | codex sandbox -- cmd |
codex completion | Generate shell completions (bash, zsh, fish, elvish, PowerShell) | codex completion zsh |
codex update | Check for updates and install the new version | codex update |
codex execpolicy | Check exec-policy rule files before saving | codex execpolicy check --rules rules.toml -- npm test |
codex mcp-server | Run Codex itself as an MCP server (stdio transport) | codex mcp-server |
codex plugin marketplace | Manage plugin marketplace sources (add, remove, upgrade) | codex plugin marketplace add URL |
codex remote-control | Start a headless app server, controllable from the Codex app or Chrome extension (since 0.130) | codex remote-control |
Note
codex exec is the command you'll use most for automation. It runs tasks non-interactively and prints the result to stdout. Perfect for scripts and CI/CD pipelines.codex exec: Flags for Non-Interactive Execution
codex exec is your workhorse for automated workflows. Without any flags, Codex waits for human approval, and scripts hang. So always set a sandbox mode.
# Standard pattern for automated execution
codex exec -s workspace-write -m gpt-5.5 "your prompt"
# Maximum reasoning depth
codex exec -s workspace-write -m gpt-5.5 \
-c model_reasoning_effort='"xhigh"' "complex task"
# Read-only for analysis (no file changes)
codex exec -s read-only -m gpt-5.5 "Analyze the architecture"Flag | Description | Example |
|---|---|---|
--model, -m | Overrides the model from your config | -m gpt-5.5 |
--sandbox, -s | Sandbox mode: read-only, workspace-write, or danger-full-access | -s workspace-write |
--ask-for-approval, -a | Approval policy: untrusted, on-failure, on-request, never | -a on-request |
--cd, -C | Sets the working directory for the agent | -C /path/to/project |
--add-dir | Grants additional writable directories | --add-dir ../backend |
--image, -i | Attaches images to the prompt (repeatable) | -i screenshot.png |
--config, -c | Overrides config.toml values (TOML syntax) | -c model_reasoning_effort='"xhigh"' |
--profile, -p | Loads a named config profile from config.toml | -p fast-profile |
--enable / --disable | Enables or disables a feature flag for this run | --enable search_tool |
--json | Outputs events as JSONL (one JSON line per event) | codex exec --json "..." |
--output-last-message, -o | Saves the agent's last message to a file | -o /tmp/result.txt |
--output-schema | JSON Schema file that constrains the final response | --output-schema schema.json |
--ephemeral | Session is not persisted to disk | codex exec --ephemeral "..." |
--skip-git-repo-check | Allows running outside a Git repo | codex exec --skip-git-repo-check "..." |
--color | Controls ANSI colors: always, never, auto | --color never |
--oss | Uses the local open-source provider (Ollama) | codex exec --oss "..." |
--full-auto | Deprecated. Alias for ,[object Object],. Use ,[object Object], directly instead | codex exec --full-auto "..." |
Warning
--full-auto is deprecated. Use -s workspace-write instead (or -s workspace-write -a on-request for the same behavior).Common Patterns
# Attach images (screenshots, design specs)
codex exec -s workspace-write -m gpt-5.5 -i screenshot.png "Implement this UI"
# Multiple writable directories
codex exec -s workspace-write -C apps/frontend --add-dir ../backend "Sync API types"
# JSON output for scripts
codex exec -s workspace-write --json "List all TODO comments"
# Save the result to a file
codex exec -s workspace-write -o /tmp/result.txt "Summarize this codebase"
# Structured output with JSON Schema
codex exec -s workspace-write --output-schema schema.json "Extract all API endpoints"
# Pipe the prompt via stdin
cat prompt.txt | codex exec -s workspace-write -
# Use a config profile
codex exec -s workspace-write -p thorough "Thorough analysis"
# Local open-source model (Ollama)
codex exec --oss -s workspace-write "Explain this function"Code Review
codex review analyzes code changes non-interactively and prints the results to stdout. It doesn't modify files.
Flag | Description | Example |
|---|---|---|
--uncommitted | Reviews staged, unstaged, and untracked changes | codex review --uncommitted |
--base | Reviews changes against a base branch | codex review --base main |
--commit | Reviews a specific commit | codex review --commit abc123 |
--title | Optional title for the review summary | codex review --title "Add auth" |
PROMPT | Custom review instructions (can also be piped via stdin with -) | codex review "Focus on security" |
# Review uncommitted changes (staged + unstaged + untracked)
codex review --uncommitted
# Review changes against a branch (before opening a PR)
codex review --base main
# Review a specific commit
codex review --commit abc123
# Review with a title and a custom focus
codex review --base main --title "Add auth" "Focus on security"
# Review via exec with JSON output
codex exec review --uncommitted --jsonSession Management
Codex stores sessions locally under ~/.codex/sessions/. You can resume them any time, fork them, or pick them up non-interactively.
# Interactive: open the session picker
codex resume
# Interactive: resume the most recent session directly
codex resume --last
# Non-interactive: resume the latest session with a new prompt
codex exec resume --last -s workspace-write -m gpt-5.5 \
"Now add error handling"
# Resume a specific session by UUID
codex exec resume 7f9f9a2e-1b3c-4c7a... -s workspace-write -m gpt-5.5 \
"Implement the plan"
# Fork a session (new thread from existing context)
codex fork --last# Apply a diff from a local session
codex apply TASK_ID
# Apply a diff from a cloud task
codex cloud apply TASK_ID
# Apply a specific attempt (when using --attempts N)
codex cloud apply TASK_ID --attempt 2Tip
Sessions started with
--ephemeral aren't saved to disk. Use this for quick one-off questions where you don't need any history.Codex Cloud
Codex Cloud runs tasks in sandboxed remote environments. All subcommands are non-interactive. The --env flag is required.
Flag | Description | Example |
|---|---|---|
--env | Required: target environment ID for the cloud task | --env ENV_ID |
--attempts | Number of attempts (best-of-N), default: 1, max: 4 | --attempts 3 |
--branch | Git branch the task should run on | --branch feature/auth |
--json | Machine-readable JSON output (for codex cloud list) | codex cloud list --json |
--limit | Maximum number of tasks returned (1-20) | codex cloud list --limit 5 |
--cursor | Pagination cursor from the previous call | codex cloud list --cursor CURSOR |
--attempt | Attempt number for diff/apply (when using --attempts N) | codex cloud diff TASK_ID --attempt 2 |
# Submit a task
codex cloud exec --env ENV_ID "Refactor the payment module"
# Best-of-3: run three attempts
codex cloud exec --env ENV_ID --attempts 3 "Fix the flaky test"
# Run on a specific branch
codex cloud exec --env ENV_ID --branch feature/auth "Add OAuth"
# List tasks
codex cloud list
codex cloud list --json --limit 5
# Check the status
codex cloud status TASK_ID
# Show the diff (specific attempt)
codex cloud diff TASK_ID --attempt 2Sandbox Modes
The sandbox limits what Codex can do on your system. You pick the mode with -s or --sandbox.
Mode | Read | Write | Network | When to use |
|---|---|---|---|---|
read-only | Anywhere | Nowhere | No | Questions, explanations, code analysis |
workspace-write | Anywhere | Working dir only | No | Default for most tasks |
danger-full-access | Anywhere | Anywhere | Yes | Only when truly needed (e.g., installing packages) |
Codex also ships with a codex sandbox command that lets you run any command inside the sandbox without involving the agent:
# Run a command in the sandbox (macOS)
codex sandbox macos -- npm test
# Log denied accesses for debugging
codex sandbox macos --log-denials -- ./build.sh
# Linux (Landlock + seccomp)
codex sandbox linux -- python3 script.pyApproval Policies
Approval policies control when Codex asks for permission before running a command. You set them with -a or --ask-for-approval.
Policy | Behavior |
|---|---|
untrusted | Only trusted commands (ls, cat, sed) run without approval |
on-failure | All commands run; approval only on failure |
on-request | The model decides when to ask for approval |
never | Never asks for approval; failures go straight back to the model |
Note
Inside the interactive TUI you switch approval mode with
/permissions. Three presets are available: Auto (default), Read Only, and Full Access.MCP Servers (Model Context Protocol)
Codex can connect to MCP servers for extra tools (databases, APIs, GitHub, and more). All management commands are non-interactive.
# List configured servers
codex mcp list
codex mcp list --json
# Show a server's config
codex mcp get my-server
codex mcp get my-server --json
# Add a stdio server
codex mcp add my-server -- npx -y @my/mcp-server
codex mcp add my-server --env API_KEY=sk-123 -- node server.js
# Add an HTTP server
codex mcp add my-server --url https://mcp.example.com/sse
codex mcp add my-server --url https://mcp.example.com \
--bearer-token-env-var MY_TOKEN_VAR
# Remove a server
codex mcp remove my-server
# OAuth login for an MCP server
codex mcp login my-server --scopes "read,write"
codex mcp logout my-serverTip
With
codex mcp-server you can run Codex itself as an MCP server. That makes it possible to plug Codex into other tools that speak MCP.Slash Commands (CLI and App)
Slash commands are available in the interactive TUI (started with codex) and in the desktop app. Type / in the composer to open the list. While a task is running, you can type a slash command and press Tab to queue it for the next turn.
The CLI TUI has far more slash commands than the app. The "Since" column shows the Codex version a command is documented from in the official release notes (where available, otherwise "n/a").
Command | Parameter | Since | Description |
|---|---|---|---|
/agent | 0.95 | Switch the active agent thread | |
/apps | 0.93 | Browse connectors and apps and insert them into the prompt | |
/approve | 0.129 | Approve one retry after a denied auto review | |
/archive | 0.136 | Archive the current session and exit Codex | |
/clear | 0.105 | Clear the terminal and start a fresh chat | |
/compact | 0.11 | Summarize the visible conversation to free tokens | |
/copy | 0.105 | Copy the latest completed Codex output (also ,[object Object],) | |
/debug-config | 0.96 | Print config layers and diagnostics | |
/delete | 0.140 | Permanently delete the current session and exit Codex | |
/diff | 0.23 | Show the Git diff, including untracked files | |
/exit | 0.53 | Exit the CLI (alias ,[object Object],) | |
/experimental | 0.74 | Toggle experimental features on or off | |
/fast | on | off | status | 0.110 | Toggle the Fast service tier |
/feedback | 0.50 | Send logs to the Codex maintainers (also App) | |
/fork | 0.88 | Fork the current conversation into a new thread | |
/goal | goal | pause | resume | clear | 0.128 | Set, pause, or clear a task goal |
/hooks | 0.129 | View and manage lifecycle hooks | |
/ide | text | 0.129 | Include open files, selection, and IDE context |
/import | 0.140 | Import Claude Code setup, project files, and chats | |
/init | 0.28 | Generate an AGENTS.md scaffold as project context | |
/keymap | 0.129 | Remap the TUI keyboard shortcuts | |
/logout | n/a | Sign out of Codex | |
/mcp | verbose | 0.23 | List the configured MCP tools (also App) |
/memories | n/a | Configure memory use and generation | |
/mention | path | n/a | Attach a file to the conversation |
/model | model | 0.23 | Choose the active model and reasoning effort |
/new | 0.59 | Start a new conversation in the same CLI session | |
/permissions | 0.89 | Set what Codex can do without asking first | |
/personality | style | 0.92 | Choose a communication style for responses |
/plan | prompt | 0.93 | Switch to plan mode (optional inline prompt) |
/plugins | 0.117 | Browse installed and discoverable plugins | |
/ps | 0.76 | Show experimental background terminals | |
/raw | on | off | 0.129 | Toggle raw scrollback mode |
/resume | 0.65 | Resume a saved session via the session picker | |
/review | 0.39 | Ask Codex to review your working tree (also App) | |
/sandbox-add-read-dir | directory | n/a | Grant the sandbox read access to a directory (Windows only) |
/side | text | 0.122 | Start an ephemeral side conversation (alias /btw) |
/skills | 0.65 | Browse and use skills | |
/status | 0.23 | Show model, approval policy, writable paths, and token usage (also App) | |
/statusline | 0.99 | Configure the TUI status-line fields | |
/stop | 0.115 | Stop all background terminals | |
/theme | 0.105 | Choose a syntax-highlighting theme | |
/title | 0.117 | Configure the terminal window or tab title | |
/usage | daily | weekly | cumulative | 0.140 | View token usage or redeem a rate-limit reset |
/vim | 0.129 | Toggle Vim mode for the composer |
Keyboard Shortcuts: CLI (TUI)
These shortcuts work in the interactive terminal interface (started with codex). You can remap them with /keymap.
Shortcut | Description | Context |
|---|---|---|
Ctrl+C | Cancels the current execution | While the agent is working |
Ctrl+D | Closes the CLI | When the input buffer is empty |
Ctrl+G | Opens external editor (VISUAL or EDITOR) | For long prompts |
Ctrl+L | Clears the screen (without starting a new chat) | When the terminal gets too cluttered |
Ctrl+O | Copies the last response to the clipboard | After a response |
Ctrl+R | Reverse search through prompt history | In the composer |
Alt+, | Lowers the reasoning depth | During the session |
Alt+. | Raises the reasoning depth | During the session |
Up / Down | Navigates the draft history in the composer | In the input field |
Tab | Queues follow-up text, slash commands, or shell commands | While the agent is working |
Esc + Esc | Edits the previous user message | In the composer |
@ | Fuzzy file search for attaching files | In the input field |
! | Runs a shell command directly | At the start of the input |
Keyboard Shortcuts: Codex App
The desktop app (started with codex app) has its own shortcuts that follow common IDE conventions. On Windows, replace Cmd with Ctrl.
Shortcut | Description |
|---|---|
Cmd+Shift+P / Cmd+K | Opens the command palette |
Cmd+, | Opens settings |
Cmd+O | Opens a folder |
Cmd+N / Cmd+Shift+O | New thread |
Cmd+F | Find in thread |
Cmd+B | Toggle sidebar |
Cmd+Option+B | Toggle diff panel |
Cmd+J | Toggle terminal |
Cmd+Shift+[ / ] | Switch to previous / next thread |
Cmd+[ / ] | Navigate back / forward |
Cmd++ / Cmd+- | Increase / decrease font size |
Ctrl+L | Clear terminal |
Ctrl+M | Start dictation |
Note
The app also supports deeplinks via the
codex:// scheme, for example codex://settings for settings or codex://new?prompt=your+prompt for a new thread with a prompt.Configuration (config.toml)
Codex config lives at ~/.codex/config.toml. You can set defaults and define named profiles.
Setting | Description | Possible values |
|---|---|---|
model | Default model for all sessions | [object Object], (recommended), ,[object Object],, ,[object Object],, ,[object Object] |
model_reasoning_effort | Reasoning depth for complex tasks | [object Object],, ,[object Object],, ,[object Object],, ,[object Object] |
personality | Communication style of the agent | [object Object],, ,[object Object],, ,[object Object] |
web_search | Web search mode | [object Object], (default), ,[object Object],, ,[object Object] |
# ~/.codex/config.toml
# Default settings
model = "gpt-5.5"
model_reasoning_effort = "high"
# Profile for quick tasks
[profiles.quick]
model = "gpt-4.1-mini"
model_reasoning_effort = "low"
# Profile for thorough work
[profiles.thorough]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
# Project trust level
[projects."/path/to/project"]
trust_level = "trusted"# Override a single value
codex exec -s workspace-write -c model='"gpt-5.5"' "Task"
# Set sandbox permissions
codex exec -s workspace-write \
-c 'sandbox_permissions=["disk-full-read-access"]' "Task"
# Load a profile with -p
codex exec -s workspace-write -p quick "Quick question"Feature Flags
Feature flags control both experimental and stable features. Changes via enable and disable are written permanently to config.toml. Per-run toggles with --enable and --disable only apply to the current run.
# List all feature flags with status and maturity
codex features list
# Permanently enable / disable a feature
codex features enable search_tool
codex features disable shell_snapshot
# Enable for this run only (not persistent)
codex exec -s workspace-write --enable search_tool \
--disable shell_snapshot "Task"Global Flags
These flags are available on almost every Codex command:
Flag | Description | Example |
|---|---|---|
--config, -c | Overrides config.toml values. Dotted paths for nesting. Values are parsed as TOML. | -c model_reasoning_effort='"high"' |
--enable | Enables a feature flag for this run (repeatable) | codex --enable search_tool |
--disable | Disables a feature flag for this run (repeatable) | codex --disable search_tool |
--help, -h | Shows help | codex --help |
--version, -V | Shows the version number | codex --version |
Troubleshooting
Problem | Likely cause | Solution |
|---|---|---|
| Authentication fails | Stale token or wrong API key | Run codex logout, then codex login again |
| Codex hangs on codex exec | No sandbox mode set (waiting for approval) | Always pass -s workspace-write or -a on-request |
| Command blocked in sandbox | Network access or write access outside the working directory | Use -s danger-full-access (only when needed) |
| MCP server doesn't connect | Missing dependencies or wrong path | Check codex mcp get server-name, then remove and add again |
| Session won't resume | Session was started with --ephemeral | Restart without --ephemeral so sessions are saved |
| Cloud task shows no diff | Task is still running or has failed | Check codex cloud status TASK_ID, then try again |
# Diagnose the config layers
# (in the interactive TUI)
/debug-config
# Show available models as JSON
codex debug models
# Show only the bundled model catalog (no API refresh)
codex debug models --bundled
# Validate exec policy rules (before saving)
codex execpolicy check --rules rules.toml -- npm test
# Log sandbox denials (debugging)
codex sandbox macos --log-denials -- ./build.sh
