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 30 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. Sorted by CLI and App so you see at a glance what works where. It's the most thorough Codex reference you'll find in English.
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)
- 34 slash commands in the interactive CLI TUI, 5 in the desktop app. The tables show exactly what's available where
- 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 "Available in" column tells you where each command works.
Command | Description | Available in |
|---|---|---|
codex | Starts the interactive TUI session in the terminal | CLI |
codex app | Launches the Codex desktop app (macOS/Windows) | App |
codex exec | Runs a task non-interactively and streams output to stdout | CLI |
codex exec resume | Resumes a previous session non-interactively | CLI |
codex review | Code review (uncommitted changes, branch diff, or commit) | CLI |
codex apply | Applies a diff from a Codex session or cloud task | CLI |
codex resume | Resumes an interactive session via session picker | CLI |
codex fork | Forks a session into a new thread | CLI |
codex cloud exec | Submits a cloud task in a sandboxed environment | CLI |
codex cloud list | Lists cloud tasks (with filter and pagination) | CLI |
codex cloud status | Shows the status of a cloud task | CLI |
codex cloud diff | Shows the diff produced by a cloud task | CLI |
codex cloud apply | Applies a cloud task diff locally | CLI |
codex mcp add | Adds an MCP server (stdio or HTTP) | CLI |
codex mcp list | Lists configured MCP servers | CLI |
codex mcp get | Shows the config for a specific MCP server | CLI |
codex mcp remove | Removes an MCP server | CLI |
codex mcp login | OAuth login for an MCP server | CLI |
codex mcp logout | Removes OAuth credentials for an MCP server | CLI |
codex features list | Shows feature flags with status and maturity stage | CLI |
codex features enable/disable | Permanently enables or disables a feature flag | CLI |
codex login | Sign in via OAuth or API key | CLI |
codex login status | Shows current login status | CLI |
codex logout | Removes stored credentials | CLI |
codex sandbox | Runs a command inside the Codex sandbox (macOS/Linux/Windows) | CLI |
codex completion | Generates shell completions (bash, zsh, fish, elvish, PowerShell) | CLI |
codex update | Checks for updates and installs a new version | CLI |
codex execpolicy | Validates exec policy rule files before saving | CLI |
codex mcp-server | Runs Codex itself as an MCP server (stdio transport) | CLI |
codex plugin marketplace | Manages plugin marketplace sources (add, remove, upgrade) | CLI |
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 "Available in" column shows you where each one works.
Command | Description | Available in |
|---|---|---|
/agent | Switches the active agent thread | CLI |
/apps | Browses and inserts connectors/apps | CLI |
/clear | Clears the terminal and starts a new chat | CLI |
/compact | Summarizes the conversation to free up tokens | CLI |
/copy | Copies the last response to the clipboard (also ,[object Object],) | CLI |
/debug-config | Prints config layer diagnostics | CLI |
/diff | Shows the Git diff including untracked files | CLI |
/exit | Closes the CLI session (alias: ,[object Object],) | CLI |
/experimental | Toggles optional features (Apps, Smart Approvals, Goals) | CLI |
/fast | Toggles Fast mode (,[object Object],, ,[object Object],, ,[object Object],) | CLI |
/feedback | Sends feedback and logs to the developers | CLI + App |
/fork | Branches the current conversation into a new thread | CLI |
/goal | Sets a persistent task objective (,[object Object],, ,[object Object],, ,[object Object],) | CLI |
/init | Generates an AGENTS.md project context file | CLI |
/keymap | Inspects and updates keyboard shortcut bindings for the TUI | CLI |
/logout | Signs out of Codex | CLI |
/mcp | Lists MCP tools (,[object Object], for details) | CLI + App |
/mention | Attaches files to the conversation | CLI |
/model | Switches the active AI model | CLI |
/new | Starts a fresh conversation in the same CLI instance | CLI |
/permissions | Configures approval mode (Auto, Read Only, Full Access) | CLI |
/personality | Changes communication style (,[object Object],, ,[object Object],, ,[object Object],) | CLI |
/plan | Activates plan mode with an optional inline prompt | CLI |
/plan-mode | Toggles multi-step planning mode | App |
/plugins | Manages installed plugins (install, toggle, inspect) | CLI |
/ps | Shows background terminals | CLI |
/resume | Loads a previous session via the session picker | CLI |
/review | Analyzes changes in the working tree (code review) | CLI + App |
/sandbox-add-read-dir | Grants the sandbox read access to a directory (Windows only) | CLI |
/side | Starts an ephemeral side conversation | CLI |
/status | Shows active model, approval policy, writable roots, and token usage | CLI + App |
/statusline | Configures items in the TUI footer | CLI |
/stop | Halts all background terminals | CLI |
/title | Configures items in the terminal title | CLI |
Keyboard Shortcuts: CLI (TUI)
These shortcuts work in the interactive terminal interface (started with codex). You can remap them with /keymap.
Shortcut | Function | 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 | Function |
|---|---|
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 |
|---|---|
--config, -c | Overrides config.toml values. Dotted paths for nesting. Values are parsed as TOML. |
--enable | Enables a feature flag for this run (repeatable) |
--disable | Disables a feature flag for this run (repeatable) |
--help, -h | Shows help |
--version, -V | Shows the version number |
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 --rules rules.toml -- npm test
# Log sandbox denials (debugging)
codex sandbox macos --log-denials -- ./build.sh
