Skip to main content

Codex Commands: The Complete Reference

Codex CLI commands and slash commands with introduction versions, plus flags, keyboard shortcuts, and examples for sessions, plugins, and cloud tasks.

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 and typed codex into your terminal. How do you resume a session, start a review, or choose another model?

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.

Here are the CLI commands and slash commands with their introduction versions, plus key flags and keyboard shortcuts for the CLI and app. For a direct comparison, see Claude Code vs. OpenAI Codex.

TL;DRKey Takeaways
  • You install Codex CLI with npm or Homebrew, start it with codex, and sign in with a ChatGPT account or an API key
  • The 59 slash commands control the model, permissions, sessions, and other TUI features
  • Three sandbox modes and the two CLI approval policies, on-request and never, control shell access and approvals
  • With codex exec you run tasks non-interactively, for example in scripts

1. Installing and Starting Codex

Codex CLI installs via npm or Homebrew. Its source code is open on GitHub under the Apache 2.0 license. On first launch, Codex asks you to sign in with your ChatGPT account or an API key.

Installation
# Install via npm
npm install -g @openai/codex

# Or via Homebrew
brew install --cask codex
Authentication
# Sign in interactively (opens browser for OAuth)
codex login

# Sign in with an API key
printenv OPENAI_API_KEY | codex login --with-api-key

# Check login status
codex login status

# Sign out
codex logout
Starting Codex
# 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-6.1-sol "Refactor auth.ts"

# Launch the desktop app
codex app

2. 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.

The command lists cover Codex CLI 0.166.0, checked on October 31, 2026. “Since version” identifies the earliest checked regular Rust release containing each command name. ≤ 0.2 means the command was already present in the first release checked, 0.2.0.

For codex mcp, 0.35 marks the management commands. In 0.34, the same command name started an MCP server.

codex
Since version
≤ 0.2
Description
Start an interactive TUI session in the terminal
Example
codex
codex app
Since version
0.95
Description
Launch the ChatGPT desktop app or its installer if it is missing. macOS opens a workspace path; Windows prints it to open.
Example
codex app
codex agents
Since version
0.149
Description
Browse agent sessions on the local app-server daemon
Example
codex agents
codex app-server
Since version
0.43
Description
Experimental: start the app server for development, debugging, or remote connections
Example
codex app-server --listen ws://127.0.0.1:4500
codex apply
Since version
0.6
Description
Apply the latest diff from a Codex cloud chat locally (alias: codex a)
Example
codex apply TASK_ID
codex archive
Since version
0.136
Description
Archive a saved session without deleting its transcript
Example
codex archive SESSION
codex cloud
Since version
0.43
Description
Experimental: browse or run cloud tasks from the terminal (alias: codex cloud-tasks)
Example
codex cloud list
codex exec
Since version
≤ 0.2
Description
Run a task non-interactively and stream output to stdout (alias: codex e)
Example
codex exec "Fix bug"
codex exec resume
Since version
0.35
Description
Resume a previous session non-interactively
Example
codex exec resume --last "Continue task"
codex exec fork
Since version
0.148
Description
Fork a previous session into a new thread non-interactively
Example
codex exec fork SESSION_ID "Try an alternative"
codex exec-server
Since version
0.119
Description
Experimental: start the exec server for remote environments
Example
codex exec-server --listen ws://127.0.0.1:8787
codex review
Since version
0.65
Description
Code review (uncommitted, branch diff, or commit)
Example
codex review --uncommitted
codex resume
Since version
0.35
Description
Resume an interactive session (session picker)
Example
codex resume
codex fork
Since version
0.81
Description
Fork a session into a new thread
Example
codex fork
codex unarchive
Since version
0.136
Description
Restore an archived session
Example
codex unarchive SESSION
codex delete
Since version
0.140
Description
Permanently delete a saved session
Example
codex delete SESSION
codex cloud exec
Since version
0.47
Description
Submit a cloud task in a sandbox environment
Example
codex cloud exec --env ENV_ID "..."
codex cloud list
Since version
0.88
Description
List cloud tasks (with filter and pagination)
Example
codex cloud list
codex cloud status
Since version
0.66
Description
Show the status of a cloud task
Example
codex cloud status ID
codex cloud diff
Since version
0.66
Description
Show the diff of a cloud task
Example
codex cloud diff ID
codex cloud apply
Since version
0.66
Description
Apply a cloud task diff locally
Example
codex cloud apply ID
codex debug
Since version
≤ 0.2
Description
Experimental diagnostics for the model catalog, prompt input, and app server
Example
codex debug models --bundled
codex debug models
Since version
Not documented
Description
Print the model catalog Codex currently sees as JSON. With --bundled, print only the bundled catalog without refreshing.
Example
codex debug models --bundled
codex debug prompt-input
Since version
0.119
Description
Print the model-visible prompt input, including system instructions, as JSON
Example
codex debug prompt-input --help
codex debug app-server send-message-v2
Since version
0.95
Description
Experimental: send a message through the built-in app-server test client
Example
codex debug app-server send-message-v2 --help
codex doctor
Since version
0.131
Description
Check installation, configuration, sign-in, runtime, and Git health. Since 0.166, --network-only limits the run to configuration, network, provider HTTP, and WebSocket checks.
Example
codex doctor --summary
codex mcp
Since version
0.35
Description
Manage external MCP servers
Example
codex mcp list
codex mcp add
Since version
0.35
Description
Add an MCP server (stdio or HTTP)
Example
codex mcp add name -- cmd
codex mcp list
Since version
0.35
Description
List configured MCP servers
Example
codex mcp list
codex mcp get
Since version
0.35
Description
Show an MCP server's configuration
Example
codex mcp get name
codex mcp remove
Since version
0.35
Description
Remove an MCP server
Example
codex mcp remove name
codex mcp login
Since version
0.45
Description
OAuth login for an MCP server
Example
codex mcp login name
codex mcp logout
Since version
0.45
Description
Remove stored OAuth credentials. With Enterprise Managed Auth (EMA), removes the shared authorization used by the affected MCP servers.
Example
codex mcp logout name
codex features
Since version
0.47
Description
List or manage feature flags
Example
codex features list
codex login
Since version
≤ 0.2
Description
Sign in via OAuth or API key
Example
codex login
codex login status
Since version
0.11
Description
Show the current login status
Example
codex login status
codex logout
Since version
0.15
Description
Remove stored credentials
Example
codex logout
codex sandbox
Since version
0.45
Description
Run a command in the Codex sandbox (macOS/Linux/Windows)
Example
codex sandbox -- cmd
codex sandbox uninstall
Since version
0.162
Description
Remove the system-wide accounts and network rules for the legacy Windows sandbox. Run as Administrator after stopping apps that use it and its provisioning service, if installed. CODEX_HOME, including sandbox directories and filesystem permissions, is preserved.
Example
codex sandbox uninstall
codex completion
Since version
0.4
Description
Generate shell completions (bash, zsh, fish, elvish, PowerShell)
Example
codex completion zsh
codex update
Since version
0.126
Description
Check for updates and install the new version
Example
codex update
codex execpolicy
Since version
0.62
Description
Check exec-policy rule files before saving
Example
codex execpolicy check --rules rules.rules -- npm test
codex execpolicy check
Since version
0.62
Description
Evaluate rule files and show whether a command would be allowed, prompted, or blocked
Example
codex execpolicy check --rules rules.rules -- npm test
codex plugin
Since version
0.122
Description
Install, list, or remove plugins from configured marketplaces
Example
codex plugin list
codex plugin marketplace
Since version
0.122
Description
Manage plugin marketplace sources (add, remove, upgrade)
Example
codex plugin marketplace add URL
codex plugin marketplace add
Since version
0.122
Description
Add a plugin marketplace source
Example
codex plugin marketplace add https://github.com/org/marketplace
codex plugin marketplace list
Since version
0.122
Description
List configured plugin marketplace sources
Example
codex plugin marketplace list
codex plugin marketplace upgrade
Since version
0.122
Description
Upgrade one or all plugin marketplaces
Example
codex plugin marketplace upgrade
codex plugin marketplace remove
Since version
0.122
Description
Remove a plugin marketplace source
Example
codex plugin marketplace remove MARKETPLACE
codex remote-control
Since version
0.130
Description
Experimental: start, stop, or pair the remotely controllable app-server daemon
Example
codex remote-control pair
codex remote-control start
Since version
0.131
Description
Start the app-server daemon with remote control enabled
Example
codex remote-control start
codex remote-control pair
Since version
0.131
Description
Requires a running daemon and prints a short-lived pairing code
Example
codex remote-control pair
codex remote-control stop
Since version
0.131
Description
Stop the app-server daemon with remote control
Example
codex remote-control stop
codex queue
Since version
0.149
Description
Queue a message for an existing local session. Since 0.166, --resume then resumes an unloaded session.
Example
codex queue --thread SESSION --message "Continue with the tests"
codex migrate-rollouts
Since version
0.148
Description
Inspect or migrate older local sessions to paginated thread history
Example
codex migrate-rollouts --verbose
codex migrate-nfs-db
Since version
0.164
Description
Experimental: migrate Codex SQLite databases for network file systems. Run only after all Codex and SQLite clients have stopped.
Example
codex migrate-nfs-db --help
codex exec review
Since version
0.65
Description
Run a review with exec output options
Example
codex exec review --uncommitted --json
codex features list
Since version
0.47
Description
Show feature flags, status, and maturity
Example
codex features list
codex features enable
Since version
0.93
Description
Enable a feature persistently
Example
codex features enable shell_snapshot
codex features disable
Since version
0.93
Description
Disable a feature persistently
Example
codex features disable shell_snapshot
codex plugin add
Since version
0.131
Description
Install a plugin from a marketplace
Example
codex plugin add PLUGIN@MARKETPLACE
codex plugin list
Since version
0.131
Description
List installed and available plugins
Example
codex plugin list --json
codex plugin remove
Since version
0.131
Description
Remove an installed plugin
Example
codex plugin remove PLUGIN@MARKETPLACE
codex app-server daemon
Since version
0.131
Description
Manage the local background server
Example
codex app-server daemon version
codex app-server daemon bootstrap
Since version
0.131
Description
Install the background server for automatic startup
Example
codex app-server daemon bootstrap
codex app-server daemon start
Since version
0.131
Description
Start the local background server
Example
codex app-server daemon start
codex app-server daemon restart
Since version
0.131
Description
Restart the local background server
Example
codex app-server daemon restart
codex app-server daemon update
Since version
Not documented
Description
Update a Codex package managed by the background server
Example
codex app-server daemon update --help
codex app-server daemon enable-remote-control
Since version
0.131
Description
Enable remote control for the background server
Example
codex app-server daemon enable-remote-control
codex app-server daemon disable-remote-control
Since version
0.131
Description
Disable remote control for the background server
Example
codex app-server daemon disable-remote-control
codex app-server daemon stop
Since version
0.131
Description
Stop the local background server
Example
codex app-server daemon stop
codex app-server daemon version
Since version
0.131
Description
Print the local CLI and running app-server versions as JSON
Example
codex app-server daemon version
codex app-server proxy
Since version
0.125
Description
Connect stdio to the local server control socket
Example
codex app-server proxy
codex app-server generate-ts
Since version
0.58
Description
Generate TypeScript bindings for the app-server protocol
Example
codex app-server generate-ts --out /tmp/codex-types
codex app-server generate-json-schema
Since version
0.58
Description
Generate JSON Schema for the app-server protocol
Example
codex app-server generate-json-schema --out /tmp/codex-schema
codex help
Since version
≤ 0.2
Description
Show help for a command
Example
codex help exec
Sources: OpenAI CLI reference
gradually.ai

3. 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.

Recommended pattern for non-interactive runs
# Standard pattern for automated execution
codex -a never exec -s workspace-write -m gpt-6.1-sol "your prompt"

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

# Read-only for analysis (no file changes)
codex exec -s read-only -m gpt-6-luna "Analyze the architecture"
--worktree
Description
Runs the session in a new managed Git worktree
Example
codex exec --worktree "..."
--thread-source
Description
Sets the source classification for new or forked threads
Example
codex exec --thread-source automation "..."
--model, -m
Description
Overrides the model from your config
Example
-m gpt-6.1-sol
--sandbox, -s
Description
Sandbox mode: read-only, workspace-write, or danger-full-access
Example
-s workspace-write
Global: --ask-for-approval, -a
Description
Sets on-request or never and must appear before the exec subcommand
Example
codex -a on-request exec "..."
--cd, -C
Description
Sets the working directory for the agent
Example
-C /path/to/project
--add-dir
Description
Grants additional writable directories
Example
--add-dir ../backend
--image, -i
Description
Attaches images to the prompt (repeatable)
Example
-i screenshot.png
--config, -c
Description
Overrides config.toml values (TOML syntax)
Example
-c model_reasoning_effort='"xhigh"'
--profile, -p
Description
Loads ~/.codex/NAME.config.toml above the base configuration
Example
-p fast-profile
--enable / --disable
Description
Enables or disables a feature flag for this run
Example
--enable shell_snapshot
--json
Description
Outputs events as JSONL (one JSON line per event)
Example
codex exec --json "..."
--output-last-message, -o
Description
Saves the agent's last message to a file
Example
-o /tmp/result.txt
--output-schema
Description
JSON Schema file that constrains the final response
Example
--output-schema schema.json
--ephemeral
Description
Session is not persisted to disk
Example
codex exec --ephemeral "..."
--cyber-access-program
Description
Since 0.161, selects an experimental Cyber access program with the OpenAI provider. Values are standard, daybreak_blue and daybreak_red, depending on your access. Not supported with review; fork requires a prompt.
Example
codex exec --cyber-access-program standard "..."
--skip-git-repo-check
Description
Allows running outside a Git repo
Example
codex exec --skip-git-repo-check "..."
--color
Description
Controls ANSI colors: always, never, auto
Example
--color never
--oss
Description
Uses a local open-source model provider
Example
codex exec --oss "..."
--local-provider
Description
Explicitly selects LM Studio or Ollama with --oss
Example
--oss --local-provider ollama
--strict-config
Description
Fails when config.toml contains fields this Codex version does not recognize
Example
codex exec --strict-config "..."
--ignore-user-config
Description
Does not load user config.toml but keeps authentication available
Example
codex exec --ignore-user-config "..."
--ignore-rules
Description
Does not load user or project exec-policy rules
Example
codex exec --ignore-rules "..."
--dangerously-bypass-approvals-and-sandbox, --yolo
Description
Bypasses approvals and the sandbox entirely. Use only inside an externally hardened environment.
Example
codex exec --yolo "..."
--approve-for-me
Description
Routes approval requests through automatic review using the workspace-write sandbox
Example
codex exec --approve-for-me "..."
--dangerously-bypass-hook-trust
Description
Runs enabled hooks without persisted trust. Use only for already vetted automation.
Example
codex exec --dangerously-bypass-hook-trust "..."

3.1 Common Patterns

codex exec examples
# Attach images (screenshots, design specs)
codex exec -s workspace-write -m gpt-6.1-sol -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"

4. Code Review

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

Choose one of --uncommitted, --base, --commit, or a custom prompt. These targets cannot be combined. --title requires --commit.

--strict-config
Description
Fails when config.toml contains fields this Codex version does not recognize
Example
codex review --strict-config --uncommitted
--uncommitted
Description
Reviews staged, unstaged, and untracked changes
Example
codex review --uncommitted
--base
Description
Reviews changes against a base branch
Example
codex review --base main
--commit
Description
Reviews a specific commit
Example
codex review --commit abc123
--title
Description
Additional title, only with --commit
Example
codex review --commit abc123 --title "Add auth"
PROMPT
Description
Custom review instructions (can also be piped via stdin with -)
Example
codex review "Focus on security"
Code review examples
# 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

5. Session Management

Codex stores non-ephemeral sessions locally. You can resume, fork, archive, or pick them up non-interactively.

Resuming sessions
# 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 -s workspace-write -m gpt-6.1-sol resume --last \
  "Now add error handling"

# Resume a specific session by UUID
codex exec -s workspace-write -m gpt-6.1-sol resume SESSION_ID \
  "Implement the plan"

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

# Fork non-interactively (session ID required)
codex exec -s workspace-write fork SESSION_ID "Try another approach"

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

# Permanently delete a session
codex delete SESSION
Applying diffs
# Apply the latest diff from a cloud task
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

6. 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.

--env
Description
Required: target environment ID for the cloud task
Example
--env ENV_ID
--attempts
Description
Number of attempts (1 to 4), default: 1
Example
--attempts 3
--branch
Description
Git branch the task should run on
Example
--branch feature/auth
--json
Description
Machine-readable JSON output (for codex cloud list)
Example
codex cloud list --json
--limit
Description
Maximum number of tasks returned (1-20)
Example
codex cloud list --limit 5
--cursor
Description
Pagination cursor from the previous call
Example
codex cloud list --cursor CURSOR
--attempt
Description
Attempt number for diff/apply (when using --attempts N)
Example
codex cloud diff TASK_ID --attempt 2
Codex Cloud examples
# 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

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

Experimental remote commands
# 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

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

# Check only configuration, network, and WebSocket
codex doctor --network-only

The daemon must be running before you pair. Keep it running while you use the remote connection, then stop it in a separate step.

Start and pair remote control
codex remote-control start
codex remote-control pair
Stop remote control later
codex remote-control stop

8. Sandbox Modes

According to OpenAI’s security documentation, the sandbox limits what Codex can do on your system. You pick the mode with -s or --sandbox.

The table describes model-generated shell commands. Network access is blocked by default in read-only and workspace-write, but you can explicitly enable it for the workspace mode. Web search, MCP servers, and connected apps use separate access paths. Add writable paths with --add-dir; protected directories such as .git can still remain read-only.

read-only
Read
According to read policy
Write
Nowhere
Network
Blocked by default
When to use
Questions, explanations, code analysis
workspace-write
Read
According to read policy
Write
Workspace, permitted roots, and temporary directories
Network
Blocked by default
When to use
Default for most tasks
danger-full-access
Read
OS permissions
Write
Anywhere
Network
Yes
When to use
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:

Sandbox utility
# 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

9. 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.

on-request
The model decides when to ask for approval
never
Never asks for approval; failures go straight back to the model

10. 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.

Managing MCP servers
# 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 -- node /path/to/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

11. CLI Slash Commands

In the interactive TUI (started with codex), type / in the composer to open the command list. While a task is running, press Tab to queue supported slash commands.

The table lists CLI TUI commands, parameters, and their introduction versions. The desktop app has a separate selection, which you can also open with /.

OpenAI’s CLI reference also lists /fast for models with an available Fast tier. It is not part of the fixed command list. Codex generates it from the model catalog and only shows it when the current model offers a Fast tier, so it is not in the table.

Versions follow the same Rust release history as the CLI overview. Renames such as /autoreview to /approve count from the version that introduced the new name. Aliases appear beside the main command and may have been added later.

/agents
Parameter
Since version
0.149
Description
View and switch between all active agent sessions
/app
Parameter
Since version
0.138
Description
Open the current session in the desktop app
/approve
Parameter
Since version
0.129
Description
Approve one retry after an auto-review denial
/apps
Parameter
Since version
0.93
Description
View and manage connected apps
/archive
Parameter
Since version
0.136
Description
Archive the current session and exit Codex
/cd
Parameter
optional path
Since version
0.149
Description
Change the current working directory
/clear
Parameter
optional name
Since version
0.105
Description
Clear the terminal and start a fresh chat
/compact
Parameter
Since version
0.11
Description
Summarize the visible conversation to free context
/config
Parameter
Since version
0.163
Description
Open settings search and change supported options immediately
/copy
Parameter
Since version
0.105
Description
Copy the latest response or part of it (also Ctrl+O)
/daemon
Parameter
Since version
0.156
Description
Manage the local background server
/daybreak
Parameter
Since version
0.161
Description
Toggle Daybreak. Requires --enable cli_daybreak, an eligible signed-in ChatGPT account with the OpenAI provider and supported models.
/debug-config
Parameter
Since version
0.97
Description
Print configuration layers and requirements diagnostics
/delete
Parameter
Since version
0.140
Description
Permanently delete the current session and its child sessions
/diff
Parameter
Since version
≤ 0.2
Description
Show the Git diff, including untracked files
/exit
Parameter
Since version
0.53
Description
Exit the CLI (alias /quit)
/experimental
Parameter
Since version
0.74
Description
Toggle experimental features
/export
Parameter
optional destination path
Since version
0.148
Description
Export the conversation as Markdown
/feedback
Parameter
Since version
0.47
Description
Send diagnostic logs to the Codex maintainers
/fork
Parameter
optional name
Since version
0.81
Description
Fork the current conversation into a new chat
/goal
Parameter
goal | edit | pause | resume | clear
Since version
0.126
Description
Set, edit, pause, or clear a task goal
/hooks
Parameter
Since version
0.129
Description
View and manage lifecycle hooks
/ide
Parameter
optional text
Since version
0.129
Description
Include open files, selection, and IDE context
/import
Parameter
Since version
0.140
Description
Import supported Claude Code or Cursor setup, projects, and chats
/init
Parameter
Since version
0.14
Description
Generate an AGENTS.md scaffold for project context
/keymap
Parameter
debug
Since version
0.126
Description
Remap TUI keyboard shortcuts or view their diagnostics
/logout
Parameter
Since version
0.15
Description
Sign out of Codex
/mcp
Parameter
verbose | login <name>
Since version
0.23
Description
List MCP tools; verbose shows details. /mcp login <name> starts server sign-in from an active session, available since 0.161.
/memories
Parameter
Since version
0.121
Description
Configure memory use and generation
/mention
Parameter
Since version
0.21
Description
Open file search to add a mention to the prompt
/model
Parameter
[model] [--reasoning=<level>] [--speed=<tier>]
Since version
0.23
Description
Choose the active model and, when available, reasoning effort
/new
Parameter
optional name
Since version
≤ 0.2
Description
Start a new chat in the same CLI session
/permissions
Parameter
[profile]
Since version
0.89
Description
Set what Codex can do without asking first
/pets
Parameter
ID | off
Since version
0.131
Description
Choose or hide a terminal pet (alias /pet)
/plan
Parameter
optional prompt
Since version
0.93
Description
Switch to plan mode
/plugins
Parameter
Since version
0.117
Description
Browse installed and discoverable plugins
/presets
Parameter
Since version
0.164
Description
Choose and manage up to ten reusable prompts and slash commands
/ps
Parameter
Since version
0.76
Description
Show background terminals and their recent output
/pwd
Parameter
Since version
0.149
Description
Show the current working directory (alias /cwd)
/raw
Parameter
on | off
Since version
0.129
Description
Toggle raw scrollback mode
/recap
Parameter
Since version
0.151
Description
Summarize the current conversation
/rename
Parameter
optional name
Since version
0.93
Description
Rename the current chat
/resume
Parameter
optional ID or name
Since version
0.65
Description
Resume a saved session directly or through the session picker
/review
Parameter
optional instructions
Since version
0.39
Description
Open review options or review with custom instructions
/setup-default-sandbox
Parameter
Since version
0.100
Description
Set up the elevated default sandbox (Windows only)
/side
Parameter
optional text
Since version
0.122
Description
Start an ephemeral side conversation in a temporary fork (alias /btw)
/skills
Parameter
Since version
0.65
Description
Browse and use skills
/status
Parameter
Since version
0.14
Description
Show the model, approval policy, writable roots, and token usage
/statusline
Parameter
[<item...> | --clear] [--colors|--no-colors]
Since version
0.99
Description
Configure TUI status-line fields
/stop
Parameter
Since version
0.115
Description
Stop all background terminals (alias /clean)
/subagents
Parameter
Since version
0.115
Description
Switch between this session's subagents
/theme
Parameter
Since version
0.105
Description
Choose a syntax-highlighting theme
/title
Parameter
[<item...> | --clear]
Since version
0.117
Description
Configure terminal-title fields
/tui
Parameter
Since version
0.156
Description
Choose the terminal renderer for the next launch
/usage
Parameter
daily | weekly | cumulative
Since version
0.140
Description
View account token usage or request a rate-limit reset
/vim
Parameter
Since version
0.129
Description
Toggle Vim mode for the composer
/voice
Parameter
settings | mute | stop
Since version
0.155
Description
Toggle voice, open settings, or mute the microphone. Since 0.161, /voice settings also lets you choose a microphone and speaker. For microphones with at least three input channels, you can select which channels to mix.
/warnings
Parameter
Since version
0.156
Description
Show retained warnings and diagnostic details
/worktree
Parameter
Since version
0.154
Description
Start or continue a conversation in a new Git worktree
Sources: OpenAI CLI reference
gradually.ai

12. Keyboard Shortcuts: CLI (TUI)

These shortcuts work in the interactive terminal interface (started with codex). You can remap them with /keymap.

Ctrl+C
Description
Cancels the current execution
Context
While the agent is working
Ctrl+D
Description
Closes the CLI
Context
When the input buffer is empty
Ctrl+G
Description
Opens external editor (VISUAL or EDITOR)
Context
For long prompts
Ctrl+L
Description
Clears the screen (without starting a new chat)
Context
When the terminal gets too cluttered
Ctrl+O
Description
Copies the last response to the clipboard
Context
After a response
Ctrl+R
Description
Reverse search through prompt history
Context
In the composer
Alt+,
Description
Lowers the reasoning depth
Context
During the session
Alt+.
Description
Raises the reasoning depth
Context
During the session
Up / Down
Description
Navigates the draft history in the composer
Context
In the input field
Tab
Description
Queues follow-up text, slash commands, or shell commands
Context
While the agent is working
Esc + Esc
Description
Edits the previous user message
Context
In the composer
@
Description
Fuzzy file search for attaching files
Context
In the input field
!
Description
Runs a shell command directly
Context
At the start of the input

13. Keyboard Shortcuts: Codex App

The desktop app (started with codex app) has its own shortcuts. The table uses macOS bindings. Many Cmd shortcuts use Ctrl on Windows, but other bindings differ. See the OpenAI reference for complete platform lists. Customize bindings in Settings > Keyboard Shortcuts.

Cmd+/
Description
Open keyboard shortcuts
Ctrl+`
Description
Toggle terminal
Ctrl+Shift+G
Description
Open review tab
Ctrl+Shift+M
Description
Open model picker
Ctrl+Shift+V
Description
Start voice chat when available
Cmd+Shift+A
Description
Archive chat
Cmd+Shift+P / Cmd+K
Description
Opens the command palette
Cmd+,
Description
Opens settings
Cmd+O
Description
Opens a folder
Cmd+N / Cmd+Shift+O
Description
New thread
Cmd+F
Description
Find in thread
Cmd+B
Description
Toggle sidebar
Cmd+Option+B
Description
Switch between chat and open tabs
Cmd+J
Description
Toggle bottom panel
Cmd+Shift+[ / ]
Description
Switch to previous / next thread
Cmd+[ / ]
Description
Navigate back / forward
Cmd++ / Cmd+-
Description
Increase / decrease font size
Ctrl+L
Description
Clear terminal
Ctrl+Shift+D
Description
Start dictation when available

14. Configuration (config.toml)

According to the configuration guide, base configuration lives at ~/.codex/config.toml. Since version 0.134.0, named profiles use separate files such as ~/.codex/quick.config.toml. --profile quick layers that file over the base values. The former [profiles.quick] structure no longer belongs in your configuration.

model
Description
Default model for all sessions
Possible values
"gpt-6.1-sol", or "gpt-6-luna", depending on your access
model_reasoning_effort
Description
Reasoning depth for complex tasks
Possible values
"xhigh", "high", "medium", "low"
personality
Description
Deprecated: friendly and pragmatic no longer change the style
Possible values
"pragmatic", "friendly", "none"
web_search
Description
Web search mode
Possible values
"cached" (default), "live", "disabled"
Base configuration: ~/.codex/config.toml
# ~/.codex/config.toml

# Default settings
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

# Project trust level
[projects."/path/to/project"]
trust_level = "trusted"
Quick profile: ~/.codex/quick.config.toml
model = "gpt-6-luna"
model_reasoning_effort = "low"
Thorough profile: ~/.codex/thorough.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
Runtime overrides with -c
# Override a single value
codex exec -s workspace-write -c model='"gpt-6.1-sol"' "Task"

# Allow network access for shell commands in workspace-write
codex exec -s workspace-write \
  -c sandbox_workspace_write.network_access=true "Task"

# Load a profile with -p
codex exec -s workspace-write -p quick "Quick question"

15. 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.

Managing feature flags
# List all feature flags with status and maturity
codex features list

# Permanently enable / disable a feature
codex features enable shell_snapshot
codex features disable shell_snapshot

# Enable for this run only (not persistent)
codex exec -s workspace-write --enable shell_snapshot \
  --json "Task"

16. Global Flags

These startup options control the interactive CLI and, depending on the subcommand, other runs. Use codex help COMMAND to check which options a particular subcommand accepts.

--worktree
Description
Starts in a new managed Git worktree
Example
codex --worktree
--no-daemon
Description
Runs without the shared background server
Example
codex --no-daemon
--approve-for-me, --not-so-yolo
Description
Automatically reviews approval requests with the workspace sandbox; cannot be combined with --sandbox or --yolo
Example
codex --approve-for-me
--profile, -p
Description
Loads a named profile from NAME.config.toml
Example
codex -p thorough
--cd, -C
Description
Sets the working directory
Example
codex -C /path/to/project
--add-dir
Description
Allows additional writable paths
Example
codex --add-dir ../backend
--image, -i
Description
Attaches images to the initial prompt
Example
codex -i screenshot.png
--config, -c
Description
Overrides config.toml values. Dotted paths for nesting. Values are parsed as TOML.
Example
-c model_reasoning_effort='"high"'
--enable
Description
Enables a feature flag for this run (repeatable)
Example
codex --enable shell_snapshot
--disable
Description
Disables a feature flag for this run (repeatable)
Example
codex --disable shell_snapshot
--model, -m
Description
Chooses a model for the current run
Example
codex -m gpt-6.1-sol
--oss
Description
Uses a local open-source model provider
Example
codex --oss --local-provider ollama
--local-provider
Description
Selects LM Studio or Ollama for --oss when not already configured
Example
codex --oss --local-provider ollama
--remote
Description
Connects the TUI, agents, queue, resume, fork, session archive, deletion, and restore actions to an app server over WebSocket or a Unix socket
Example
codex --remote ws://127.0.0.1:4500
--remote-auth-token-env
Description
Reads a bearer token from an environment variable for --remote. Requires --remote and wss:// or loopback ws://
Example
--remote-auth-token-env CODEX_REMOTE_TOKEN
--sandbox, -s
Description
Chooses read-only, workspace-write, or danger-full-access
Example
-s workspace-write
--ask-for-approval, -a
Description
Sets the approval policy to on-request or never
Example
codex -a on-request
--search
Description
Switches from the default cached search to live web search
Example
codex --search "Check the current documentation"
--no-alt-screen
Description
Runs the TUI inline and preserves terminal scrollback
Example
codex --no-alt-screen
--strict-config
Description
Fails on unrecognized config.toml fields
Example
codex --strict-config
--dangerously-bypass-approvals-and-sandbox, --yolo
Description
Bypasses approvals and the sandbox. Use only inside an externally hardened environment.
Example
codex --yolo "..."
--dangerously-bypass-hook-trust
Description
Runs enabled hooks without persisted trust. Use only for already vetted automation.
Example
codex --dangerously-bypass-hook-trust "..."
--help, -h
Description
Shows help
Example
codex --help
--version, -V
Description
Shows the version number
Example
codex --version

17. Troubleshooting

Authentication fails
Likely cause
Stale token or wrong API key
Solution
Run codex logout, then codex login again
Codex hangs on codex exec
Likely cause
The approval policy requires confirmation in an unattended environment
Solution
For controlled automation, set -s workspace-write and deliberately use -a never
Command blocked in sandbox
Likely cause
Network access or write access outside the working directory
Solution
First consider --add-dir for additional write paths. Use danger-full-access deliberately
MCP server doesn't connect
Likely cause
Missing dependencies or wrong path
Solution
Check codex mcp get server-name, then remove and add again
Session won't resume
Likely cause
Session was started with --ephemeral
Solution
Restart without --ephemeral so sessions are saved
Cloud task shows no diff
Likely cause
Task is still running or has failed
Solution
Check codex cloud status TASK_ID, then try again
Codex no longer starts after an update
Likely cause
Stale or unrecognized fields in config.toml
Solution
Run codex --strict-config and codex doctor --summary
Debug commands
# 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.rules -- npm test

# Log sandbox denials (debugging)
codex sandbox --log-denials -- ./build.sh

Frequently Asked Questions

It is free to install, since Codex CLI is open source. To use it, sign in with your ChatGPT account or, after additional setup, an API key. Included usage and API costs are listed on the current OpenAI pricing and plan page.

Codex CLI runs in your terminal and is controlled with commands and flags. The Codex App is a desktop application with a graphical interface. Their commands, settings, integrations, and features are not fully identical.

codex starts an interactive terminal session. codex exec runs a task without interactive prompts and prints its output in the terminal. Add --json to receive newline-delimited JSON events, which suits scripts and CI pipelines.

Type /exit (alias /quit), or press Ctrl+D when the input is empty, to close the CLI. Ctrl+C cancels the current execution while the agent is working.

Yes. /btw is an alias for /side. It starts an ephemeral side conversation in a temporary fork, optionally with text right away.

Inside the interactive TUI, type /resume, or run codex resume from the terminal. For non-interactive use, run codex exec resume --last followed by your new prompt. Sessions started with --ephemeral are not saved. Use codex archive to clean up the picker, codex unarchive to restore a session, and codex delete to remove one permanently.

The sandbox applies to model-generated shell commands. read-only blocks writes. workspace-write permits writes in the workspace, allowed roots, and temporary directories. Network access is blocked by default in both modes but can be enabled for workspace-write. danger-full-access removes these restrictions; operating-system permissions still apply. Web search, MCP, and apps have separate connections.

Yes. Use codex -a never exec -s workspace-write for automated execution without prompts. The approval flag is global and must appear before exec. With --json you get structured JSONL output. Authenticate with an API key: printenv OPENAI_API_KEY | codex login --with-api-key. Add --skip-git-repo-check if you're running outside a Git repo.
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.