Skip to main content

Codex Commands: The Complete Reference

Every Codex CLI command, flag, slash command, and shortcut at a glance. The most thorough reference for OpenAI's coding agent.

FHFinn Hillebrandt
AI Programming
Codex Commands: The Complete Reference
Links marked with * are affiliate links. If a purchase is made through such links, we receive a commission.

You installed Codex, typed codex into your terminal, and wondered: "Okay, now what?"

Same here. OpenAI's coding agent evolves quickly. Commands for sessions, plugins, Cloud, and remote control are added while others change. Without a current 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
  • This reference covers the current CLI, from codex exec and codex review to session archives, plugins, the app server, and Codex Cloud
  • Slash commands in the composer control the model, permissions, sessions, plan mode, and other TUI features. The table lists the introduction version for all 53 commands
  • Three sandbox modes (read-only, workspace-write, danger-full-access) and three approval policies control what Codex can do on your system
  • Codex Cloud can run work in remote environments. App-server and remote-control are clearly marked experimental

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
brew install --cask 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.6-terra "Refactor auth.ts"

# Launch the desktop app
codex app

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.

Commandcodex
DescriptionStart an interactive TUI session in the terminal
Examplecodex
Commandcodex app
DescriptionLaunch the Codex desktop app (macOS/Windows)
Examplecodex app
Commandcodex agents
DescriptionBrowse agent sessions on the local app-server daemon
Examplecodex agents
Commandcodex app-server
DescriptionExperimental: start the app server for development, debugging, or remote connections
Examplecodex app-server --listen ws://127.0.0.1:4500
Commandcodex apply
DescriptionApply the latest diff from a Codex agent locally
Examplecodex apply TASK_ID
Commandcodex archive
DescriptionArchive a saved session without deleting its transcript
Examplecodex archive SESSION
Commandcodex cloud
DescriptionExperimental: browse Cloud tasks or run them from the terminal
Examplecodex cloud list
Commandcodex exec
DescriptionRun a task non-interactively, stream output to stdout
Examplecodex exec "Fix bug"
Commandcodex exec resume
DescriptionResume a previous session non-interactively
Examplecodex exec resume --last "Continue task"
Commandcodex exec fork
DescriptionFork a previous session into a new thread non-interactively
Examplecodex exec fork --last "Try an alternative"
Commandcodex exec-server
DescriptionExperimental: start the exec server for remote environments
Examplecodex exec-server --listen ws://127.0.0.1:8787
Commandcodex review
DescriptionCode review (uncommitted, branch diff, or commit)
Examplecodex review --uncommitted
Commandcodex resume
DescriptionResume an interactive session (session picker)
Examplecodex resume
Commandcodex fork
DescriptionFork a session into a new thread
Examplecodex fork
Commandcodex unarchive
DescriptionRestore an archived session
Examplecodex unarchive SESSION
Commandcodex delete
DescriptionPermanently delete a saved session
Examplecodex delete SESSION
Commandcodex cloud exec
DescriptionSubmit a cloud task in a sandbox environment
Examplecodex cloud exec --env ENV_ID "..."
Commandcodex cloud list
DescriptionList cloud tasks (with filter and pagination)
Examplecodex cloud list
Commandcodex cloud status
DescriptionShow the status of a cloud task
Examplecodex cloud status ID
Commandcodex cloud diff
DescriptionShow the diff of a cloud task
Examplecodex cloud diff ID
Commandcodex cloud apply
DescriptionApply a cloud task diff locally
Examplecodex cloud apply ID
Commandcodex debug
DescriptionExperimental diagnostics for the model catalog, prompt input, and app server
Examplecodex debug models --bundled
Commandcodex doctor
DescriptionCheck installation, configuration, sign-in, runtime, and Git health
Examplecodex doctor --summary
Commandcodex mcp
DescriptionManage external MCP servers
Examplecodex mcp list
Commandcodex mcp add
DescriptionAdd an MCP server (stdio or HTTP)
Examplecodex mcp add name -- cmd
Commandcodex mcp list
DescriptionList configured MCP servers
Examplecodex mcp list
Commandcodex mcp get
DescriptionShow an MCP server's configuration
Examplecodex mcp get name
Commandcodex mcp remove
DescriptionRemove an MCP server
Examplecodex mcp remove name
Commandcodex mcp login
DescriptionOAuth login for an MCP server
Examplecodex mcp login name
Commandcodex mcp logout
DescriptionRemove an MCP server's OAuth credentials
Examplecodex mcp logout name
Commandcodex features list
DescriptionShow feature flags with status and maturity
Examplecodex features list
Commandcodex features enable/disable
DescriptionEnable or disable a feature flag persistently
Examplecodex features enable NAME
Commandcodex login
DescriptionSign in via OAuth or API key
Examplecodex login
Commandcodex login status
DescriptionShow the current login status
Examplecodex login status
Commandcodex logout
DescriptionRemove stored credentials
Examplecodex logout
Commandcodex sandbox
DescriptionRun a command in the Codex sandbox (macOS/Linux/Windows)
Examplecodex sandbox -- cmd
Commandcodex completion
DescriptionGenerate shell completions (bash, zsh, fish, elvish, PowerShell)
Examplecodex completion zsh
Commandcodex update
DescriptionCheck for updates and install the new version
Examplecodex update
Commandcodex execpolicy
DescriptionCheck exec-policy rule files before saving
Examplecodex execpolicy check --rules rules.toml -- npm test
Commandcodex mcp-server
DescriptionRun Codex itself as an MCP server (stdio transport)
Examplecodex mcp-server
Commandcodex plugin
DescriptionInstall, list, or remove plugins from configured marketplaces
Examplecodex plugin list
Commandcodex plugin marketplace
DescriptionManage plugin marketplace sources (add, remove, upgrade)
Examplecodex plugin marketplace add URL
Commandcodex remote-control
DescriptionExperimental: start, stop, or pair the remotely controllable app-server daemon
Examplecodex remote-control pair
Commandcodex queue
DescriptionQueue a message for an existing local session
Examplecodex queue --thread SESSION --message "Continue with the tests"
Commandcodex migrate-rollouts
DescriptionInspect or migrate older local sessions to paginated thread history
Examplecodex migrate-rollouts --verbose

codex exec: Flags for Non-Interactive Execution

codex exec is your workhorse for automated workflows. Set the sandbox and approval policy deliberately, so a scripted run behaves predictably and its access remains clear.

# Standard pattern for automated execution
codex -a never exec -s workspace-write -m gpt-5.6-terra "your prompt"

# Maximum reasoning depth
codex -a on-request exec -s workspace-write -m gpt-5.6-sol \
  -c model_reasoning_effort='"xhigh"' "complex task"

# Read-only for analysis (no file changes)
codex exec -s read-only -m gpt-5.6-luna "Analyze the architecture"
Flag--model, -m
DescriptionOverrides the model from your config
Example-m gpt-5.6-terra
Flag--sandbox, -s
DescriptionSandbox mode: read-only, workspace-write, or danger-full-access
Example-s workspace-write
FlagGlobal: --ask-for-approval, -a
DescriptionSets on-request or never and must appear before the exec subcommand
Examplecodex -a on-request exec "..."
Flag--cd, -C
DescriptionSets the working directory for the agent
Example-C /path/to/project
Flag--add-dir
DescriptionGrants additional writable directories
Example--add-dir ../backend
Flag--image, -i
DescriptionAttaches images to the prompt (repeatable)
Example-i screenshot.png
Flag--config, -c
DescriptionOverrides config.toml values (TOML syntax)
Example-c model_reasoning_effort='"xhigh"'
Flag--profile, -p
DescriptionLoads a named config profile from config.toml
Example-p fast-profile
Flag--enable / --disable
DescriptionEnables or disables a feature flag for this run
Example--enable search_tool
Flag--json
DescriptionOutputs events as JSONL (one JSON line per event)
Examplecodex exec --json "..."
Flag--output-last-message, -o
DescriptionSaves the agent's last message to a file
Example-o /tmp/result.txt
Flag--output-schema
DescriptionJSON Schema file that constrains the final response
Example--output-schema schema.json
Flag--ephemeral
DescriptionSession is not persisted to disk
Examplecodex exec --ephemeral "..."
Flag--skip-git-repo-check
DescriptionAllows running outside a Git repo
Examplecodex exec --skip-git-repo-check "..."
Flag--color
DescriptionControls ANSI colors: always, never, auto
Example--color never
Flag--oss
DescriptionUses a local open-source model provider
Examplecodex exec --oss "..."
Flag--local-provider
DescriptionExplicitly selects LM Studio or Ollama with --oss
Example--oss --local-provider ollama
Flag--strict-config
DescriptionFails when config.toml contains fields this Codex version does not recognize
Examplecodex exec --strict-config "..."
Flag--ignore-user-config
DescriptionDoes not load user config.toml but keeps authentication available
Examplecodex exec --ignore-user-config "..."
Flag--ignore-rules
DescriptionDoes not load user or project exec-policy rules
Examplecodex exec --ignore-rules "..."
Flag--dangerously-bypass-approvals-and-sandbox, --yolo
DescriptionBypasses approvals and the sandbox entirely. Use only inside an externally hardened environment.
Examplecodex exec --yolo "..."
Flag--approve-for-me
DescriptionRoutes approval requests through automatic review using the workspace-write sandbox
Examplecodex exec --approve-for-me "..."
Flag--dangerously-bypass-hook-trust
DescriptionRuns enabled hooks without persisted trust. Use only for already vetted automation.
Examplecodex exec --dangerously-bypass-hook-trust "..."

Common Patterns

# Attach images (screenshots, design specs)
codex exec -s workspace-write -m gpt-5.6-terra -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 or LM Studio)
codex exec --oss --local-provider ollama -s workspace-write "Explain this function"

# Strictly validate config before an automated run
codex exec --strict-config -s workspace-write "Check the configuration"

Code Review

codex review analyzes code changes non-interactively and prints the results to stdout. It doesn't modify files.

Flag--uncommitted
DescriptionReviews staged, unstaged, and untracked changes
Examplecodex review --uncommitted
Flag--base
DescriptionReviews changes against a base branch
Examplecodex review --base main
Flag--commit
DescriptionReviews a specific commit
Examplecodex review --commit abc123
Flag--title
DescriptionOptional title for the review summary
Examplecodex review --title "Add auth"
FlagPROMPT
DescriptionCustom review instructions (can also be piped via stdin with -)
Examplecodex 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 a commit with a title
codex review --commit abc123 --title "Add auth"

# Review with a custom focus
codex review "Focus on security"

# Review via exec with JSON output
codex exec review --uncommitted --json

Session Management

Codex stores non-ephemeral sessions locally. You can resume, fork, archive, 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.6-terra \
  "Now add error handling"

# Resume a specific session by UUID
codex exec resume 7f9f9a2e-1b3c-4c7a... -s workspace-write -m gpt-5.6-terra \
  "Implement the plan"

# Fork a session (new thread from existing context)
codex fork --last

# Archive or restore a session
codex archive SESSION
codex unarchive SESSION

# Permanently delete a session
codex delete SESSION
# 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 2

Codex Cloud

Codex Cloud works with remote environments. Without a subcommand, codex cloud opens a picker. codex cloud exec submits a task directly, and requires --env.

Flag--env
DescriptionRequired: target environment ID for the cloud task
Example--env ENV_ID
Flag--attempts
DescriptionNumber of attempts (best-of-N), default: 1
Example--attempts 3
Flag--branch
DescriptionGit branch the task should run on
Example--branch feature/auth
Flag--json
DescriptionMachine-readable JSON output (for codex cloud list)
Examplecodex cloud list --json
Flag--limit
DescriptionMaximum number of tasks returned (1-20)
Examplecodex cloud list --limit 5
Flag--cursor
DescriptionPagination cursor from the previous call
Examplecodex cloud list --cursor CURSOR
Flag--attempt
DescriptionAttempt number for diff/apply (when using --attempts N)
Examplecodex 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 2

App Server and Remote Control

App-server, remote connections, and remote-control are experimental. They are for advanced setups and may change between releases. You do not need them for everyday Codex work.

# Start an app server with a WebSocket endpoint
codex app-server --listen ws://127.0.0.1:4500

# Connect the TUI to an app server
codex --remote ws://127.0.0.1:4500

# Manage the remote-control daemon
codex remote-control start
codex remote-control pair
codex remote-control stop

# Diagnose the model catalog and local installation
codex debug models --bundled
codex doctor --summary

Sandbox Modes

The sandbox limits what Codex can do on your system. You pick the mode with -s or --sandbox.

Moderead-only
ReadAnywhere
WriteNowhere
NetworkNo
When to useQuestions, explanations, code analysis
Modeworkspace-write
ReadAnywhere
WriteWorking dir only
NetworkNo
When to useDefault for most tasks
Modedanger-full-access
ReadAnywhere
WriteAnywhere
NetworkYes
When to useOnly 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 current Codex sandbox
codex sandbox -- npm test

# Log denied accesses on macOS
codex sandbox --log-denials -- ./build.sh

# Set a project folder as the working directory
codex sandbox -C apps/frontend -- npm test

Approval Policies

Approval policies control when Codex asks for permission before running a command. Set the global -a or --ask-for-approval flag before the subcommand, for example codex -a on-request exec.

Policyon-request
BehaviorThe model decides when to ask for approval
Policynever
BehaviorNever asks for approval; failures go straight back to the model

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-server

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 more slash commands than the app. The table lists currently documented commands, parameters, and their introduction versions. Individual commands may be unavailable depending on your platform, model, or enabled features.

I checked more than the release notes for this column. It lists the earliest regular Codex release whose source tree exposes the specific slash command. Renames such as /autoreview to /approve count from the version that introduced the new name.

Command/agents
Parameter
Since version0.149
DescriptionView and switch between all active agent sessions
Command/app
Parameter
Since version0.138
DescriptionOpen the current session in the desktop app
Command/apps
Parameter
Since version0.93
DescriptionBrowse apps and insert one into the prompt
Command/approve
Parameter
Since version0.129
DescriptionApprove one retry after an auto-review denial
Command/archive
Parameter
Since version0.136
DescriptionArchive the current session and exit Codex
Command/cd
Parameteroptional path
Since version0.149
DescriptionChange the current working directory
Command/clear
Parameteroptional name
Since version0.105
DescriptionClear the terminal and start a fresh chat
Command/compact
Parameter
Since version0.11
DescriptionSummarize the visible conversation to free context
Command/copy
Parameter
Since version0.105
DescriptionCopy the latest completed output (also Ctrl+O)
Command/debug-config
Parameter
Since version0.97
DescriptionPrint configuration layers and requirements diagnostics
Command/delete
Parameter
Since version0.140
DescriptionPermanently delete the current session and its child sessions
Command/diff
Parameter
Since version0.2
DescriptionShow the Git diff, including untracked files
Command/exit
Parameter
Since version0.53
DescriptionExit the CLI (alias /quit)
Command/experimental
Parameter
Since version0.74
DescriptionToggle experimental features
Command/export
Parameteroptional destination path
Since version0.148
DescriptionExport the conversation as Markdown
Command/fast
Parameter
Since version0.110
DescriptionToggle the Fast service tier when the active model offers one
Command/feedback
Parameter
Since version0.47
DescriptionSend diagnostic logs to the Codex maintainers
Command/fork
Parameter
Since version0.81
DescriptionFork the current conversation into a new chat
Command/goal
Parametergoal | edit | pause | resume | clear
Since version0.128
DescriptionSet, edit, pause, or clear a task goal
Command/hooks
Parameter
Since version0.129
DescriptionView and manage lifecycle hooks
Command/ide
Parameteroptional text
Since version0.129
DescriptionInclude open files, selection, and IDE context
Command/import
Parameter
Since version0.140
DescriptionImport supported Claude Code or Cursor setup, projects, and chats
Command/init
Parameter
Since version0.14
DescriptionGenerate an AGENTS.md scaffold for project context
Command/keymap
Parameter
Since version0.128
DescriptionRemap TUI keyboard shortcuts
Command/logout
Parameter
Since version0.15
DescriptionSign out of Codex
Command/mcp
Parameterverbose
Since version0.23
DescriptionList configured MCP tools
Command/memories
Parameter
Since version0.121
DescriptionConfigure memory use and generation
Command/mention
Parameterpath
Since version0.21
DescriptionAttach a file or folder to the conversation
Command/model
Parametermodel
Since version0.23
DescriptionChoose the active model and, when available, reasoning effort
Command/new
Parameteroptional name
Since version0.2
DescriptionStart a new chat in the same CLI session
Command/permissions
Parameter
Since version0.89
DescriptionSet what Codex can do without asking first
Command/personality
Parameter
Since version0.92
DescriptionChoose a communication style for responses
Command/pets
Parameter
Since version0.131
DescriptionChoose or hide a terminal pet (alias /pet)
Command/plan
Parameteroptional prompt
Since version0.93
DescriptionSwitch to plan mode
Command/plugins
Parameter
Since version0.117
DescriptionBrowse installed and discoverable plugins
Command/ps
Parameter
Since version0.76
DescriptionShow background terminals and their recent output
Command/pwd
Parameter
Since version0.149
DescriptionShow the current working directory (alias /cwd)
Command/raw
Parameteron | off
Since version0.129
DescriptionToggle raw scrollback mode
Command/rename
Parameteroptional name
Since version0.93
DescriptionRename the current chat
Command/resume
Parameter
Since version0.65
DescriptionResume a saved session from the session picker
Command/review
Parameter
Since version0.39
DescriptionAsk Codex to review the working tree
Command/sandbox-add-read-dir
Parameterabsolute path
Since version0.102
DescriptionGrant sandbox read access to a directory (Windows only)
Command/setup-default-sandbox
Parameter
Since version0.100
DescriptionSet up the elevated default sandbox (Windows only)
Command/side
Parameteroptional text
Since version0.122
DescriptionStart an ephemeral side conversation in a temporary fork (alias /btw)
Command/skills
Parameter
Since version0.65
DescriptionBrowse and use skills
Command/status
Parameter
Since version0.14
DescriptionShow the model, approval policy, writable roots, and token usage
Command/statusline
Parameter
Since version0.99
DescriptionConfigure TUI status-line fields
Command/stop
Parameter
Since version0.115
DescriptionStop all background terminals (alias /clean)
Command/subagents
Parameter
Since version0.115
DescriptionSwitch between this session's subagents
Command/theme
Parameter
Since version0.105
DescriptionChoose a syntax-highlighting theme
Command/title
Parameter
Since version0.117
DescriptionConfigure terminal-title fields
Command/usage
Parameterdaily | weekly | cumulative
Since version0.140
DescriptionView account token usage or request a rate-limit reset
Command/vim
Parameter
Since version0.129
DescriptionToggle 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.

ShortcutCtrl+C
DescriptionCancels the current execution
ContextWhile the agent is working
ShortcutCtrl+D
DescriptionCloses the CLI
ContextWhen the input buffer is empty
ShortcutCtrl+G
DescriptionOpens external editor (VISUAL or EDITOR)
ContextFor long prompts
ShortcutCtrl+L
DescriptionClears the screen (without starting a new chat)
ContextWhen the terminal gets too cluttered
ShortcutCtrl+O
DescriptionCopies the last response to the clipboard
ContextAfter a response
ShortcutCtrl+R
DescriptionReverse search through prompt history
ContextIn the composer
ShortcutAlt+,
DescriptionLowers the reasoning depth
ContextDuring the session
ShortcutAlt+.
DescriptionRaises the reasoning depth
ContextDuring the session
ShortcutUp / Down
DescriptionNavigates the draft history in the composer
ContextIn the input field
ShortcutTab
DescriptionQueues follow-up text, slash commands, or shell commands
ContextWhile the agent is working
ShortcutEsc + Esc
DescriptionEdits the previous user message
ContextIn the composer
Shortcut@
DescriptionFuzzy file search for attaching files
ContextIn the input field
Shortcut!
DescriptionRuns a shell command directly
ContextAt 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.

ShortcutCmd+Shift+P / Cmd+K
DescriptionOpens the command palette
ShortcutCmd+,
DescriptionOpens settings
ShortcutCmd+O
DescriptionOpens a folder
ShortcutCmd+N / Cmd+Shift+O
DescriptionNew thread
ShortcutCmd+F
DescriptionFind in thread
ShortcutCmd+B
DescriptionToggle sidebar
ShortcutCmd+Option+B
DescriptionToggle diff panel
ShortcutCmd+J
DescriptionToggle terminal
ShortcutCmd+Shift+[ / ]
DescriptionSwitch to previous / next thread
ShortcutCmd+[ / ]
DescriptionNavigate back / forward
ShortcutCmd++ / Cmd+-
DescriptionIncrease / decrease font size
ShortcutCtrl+L
DescriptionClear terminal
ShortcutCtrl+M
DescriptionStart dictation

Configuration (config.toml)

Codex config lives at ~/.codex/config.toml. You can set defaults and define named profiles.

Settingmodel
DescriptionDefault model for all sessions
Possible values"gpt-5.6-sol", "gpt-5.6-terra", or "gpt-5.6-luna", depending on your access
Settingmodel_reasoning_effort
DescriptionReasoning depth for complex tasks
Possible values"xhigh", "high", "medium", "low"
Settingpersonality
DescriptionCommunication style of the agent
Possible values"pragmatic", "friendly", "none"
Settingweb_search
DescriptionWeb search mode
Possible values"cached" (default), "live", "disabled"
# ~/.codex/config.toml

# Default settings
model = "gpt-5.6-terra"
model_reasoning_effort = "high"

# Profile for quick tasks
[profiles.quick]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

# Profile for thorough work
[profiles.thorough]
model = "gpt-5.6-sol"
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.6-terra"' "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--config, -c
DescriptionOverrides config.toml values. Dotted paths for nesting. Values are parsed as TOML.
Example-c model_reasoning_effort='"high"'
Flag--enable
DescriptionEnables a feature flag for this run (repeatable)
Examplecodex --enable search_tool
Flag--disable
DescriptionDisables a feature flag for this run (repeatable)
Examplecodex --disable search_tool
Flag--model, -m
DescriptionChooses a model for the current run
Examplecodex -m gpt-5.6-terra
Flag--oss / --local-provider
DescriptionUses a local open-source model and chooses LM Studio or Ollama when needed
Examplecodex --oss --local-provider ollama
Flag--remote
DescriptionConnects the TUI, resume, fork, and session archive actions to an app server over WebSocket or a Unix socket
Examplecodex --remote ws://127.0.0.1:4500
Flag--remote-auth-token-env
DescriptionReads a bearer token from an environment variable for --remote
Example--remote-auth-token-env CODEX_REMOTE_TOKEN
Flag--sandbox, -s
DescriptionChooses read-only, workspace-write, or danger-full-access
Example-s workspace-write
Flag--ask-for-approval, -a
DescriptionSets the approval policy to on-request or never
Examplecodex -a on-request
Flag--search
DescriptionSwitches from the default cached search to live web search
Examplecodex --search "Check the current documentation"
Flag--no-alt-screen
DescriptionRuns the TUI inline and preserves terminal scrollback
Examplecodex --no-alt-screen
Flag--strict-config
DescriptionFails on unrecognized config.toml fields
Examplecodex --strict-config
Flag--dangerously-bypass-approvals-and-sandbox, --yolo
DescriptionBypasses approvals and the sandbox. Use only inside an externally hardened environment.
Examplecodex --yolo "..."
Flag--dangerously-bypass-hook-trust
DescriptionRuns enabled hooks without persisted trust. Use only for already vetted automation.
Examplecodex --dangerously-bypass-hook-trust "..."
Flag--help, -h
DescriptionShows help
Examplecodex --help
Flag--version, -V
DescriptionShows the version number
Examplecodex --version

Troubleshooting

ProblemAuthentication fails
Likely causeStale token or wrong API key
SolutionRun codex logout, then codex login again
ProblemCodex hangs on codex exec
Likely causeThe approval policy requires confirmation in an unattended environment
SolutionFor controlled automation, set -s workspace-write and deliberately use -a never
ProblemCommand blocked in sandbox
Likely causeNetwork access or write access outside the working directory
SolutionFirst consider --add-dir for additional write paths. Use danger-full-access deliberately
ProblemMCP server doesn't connect
Likely causeMissing dependencies or wrong path
SolutionCheck codex mcp get server-name, then remove and add again
ProblemSession won't resume
Likely causeSession was started with --ephemeral
SolutionRestart without --ephemeral so sessions are saved
ProblemCloud task shows no diff
Likely causeTask is still running or has failed
SolutionCheck codex cloud status TASK_ID, then try again
ProblemCodex no longer starts after an update
Likely causeStale or unrecognized fields in config.toml
SolutionRun codex --strict-config and codex doctor --summary
# 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

FAQ

Frequently Asked Questions

FH

Finn Hillebrandt

AI Expert & Blogger

Finn Hillebrandt is the founder of Gradually AI, an SEO and AI expert. He helps online entrepreneurs simplify and automate their processes and marketing with AI. Finn shares his knowledge here on the blog in 50+ articles as well as through the AI Business Club.

Learn more about Finn and the team, follow Finn on LinkedIn, join his Facebook group for ChatGPT, OpenAI & AI Tools or do like 17,500+ others and subscribe to his AI Newsletter with tips, news and offers about AI tools and online business. Also visit his other blog, Blogmojo, which is about WordPress, blogging and SEO.