Codex CLI is OpenAI’s local coding agent for the terminal. It can inspect a repository, edit files, run commands, review changes, and continue previous work through saved sessions.
This cheat sheet is for developers who use Codex from a shell, a terminal UI, or automation scripts. It separates shell commands, interactive slash commands, CLI flags, configuration keys, environment variables, and experimental features so each command is used in the right place.
Use the tables as a working reference. Start with the stable commands, then add flags, sandbox settings, MCP servers, and non-interactive workflows as your usage gets more advanced.
Last audited: May 06, 2026
Table Of Contents
- Quick Classification
- Installation and Authentication
- Session and Conversation Commands
- Interactive Slash Commands for Sessions
- Project and Workspace Commands
- Interactive Workspace Slash Commands
- Code Editing and Review Commands
- Model, Reasoning, and Mode Controls
- Useful Model Config Keys
- Permissions, Sandbox, and Safety
- Useful Safety Config Keys
- Git and PR Workflows
- MCP, Integrations, and Tools
- MCP Config Keys
- CLI Flags
- Non-Interactive Mode
- Environment Variables
- Custom Commands and Automation
- Community, Experimental, and Deprecated Items
- Real Workflows
Quick Classification
| Type | Where it is used | Example | Notes |
|---|---|---|---|
| CLI command | Your shell | codex exec "Fix failing tests" | Runs from a terminal prompt. |
| CLI flag | After codex or a subcommand | codex --model gpt-5.5 | Changes one invocation. |
| Slash command | Inside the interactive Codex TUI | /status | Only works after codex opens the TUI. |
| Config key | ~/.codex/config.toml | sandbox_mode = "workspace-write" | Persists defaults. |
| Environment variable | Shell environment | CODEX_CA_CERTIFICATE=/path/ca.pem | Used for auth, providers, TLS, or logging. |
| Experimental command | Shell or TUI | codex mcp-server | Officially documented but may change. |
| Deprecated command or flag | Shell or TUI | --full-auto | Keep out of new workflows. |
Installation and Authentication
| Command | What it does | Notes |
|---|---|---|
npm install -g @openai/codex | Installs Codex CLI with npm. | Official install path. Requires a Node/npm environment. |
brew install --cask codex | Installs Codex CLI with Homebrew. | Official macOS install path. |
codex | Starts Codex in interactive terminal UI mode. | Stable. Run from the project root for repository-aware work. |
codex login | Starts the default ChatGPT sign-in flow. | Stable. Opens a browser when possible. |
codex login --device-auth | Uses device-code authentication. | Beta-style fallback for headless or remote environments. |
printenv OPENAI_API_KEY | codex login --with-api-key | Signs in with an API key from stdin. | Stable. Recommended by the docs for programmatic CLI workflows. |
codex login status | Prints the active authentication mode. | Stable. Exits with status 0 when logged in. Useful in scripts. |
codex logout | Removes stored Codex credentials. | Stable. Clears both API-key and ChatGPT auth. |
codex update | Checks for and applies an update when the installed release supports self-update. | Stable. Debug builds may not support self-update. |
Session and Conversation Commands
| Command | What it does | Notes |
|---|---|---|
codex | Opens a new interactive session. | Stable. Accepts global flags and an optional prompt. |
codex "Explain this codebase" | Opens the TUI with an initial prompt. | Stable. Useful for starting work with context. |
codex resume | Opens a picker for previous sessions. | Stable. Scoped to the current working directory by default. |
codex resume --last | Resumes the most recent session for the current directory. | Stable. Add --all to ignore the directory filter. |
codex resume --all | Shows sessions beyond the current directory. | Stable. Useful when work moved directories. |
codex resume <SESSION_ID> | Resumes a specific saved session. | Stable. Session IDs appear in /status and local session files. |
codex resume --include-non-interactive | Includes non-interactive sessions in the resume picker and --last selection. | Stable in the current local CLI help. |
codex fork | Forks a previous interactive session into a new thread. | Stable. Good for trying a different approach without changing the original transcript. |
codex fork --last | Forks the most recent saved session. | Stable. Add --all to include sessions from other directories. |
codex exec resume --last "Continue the fix" | Resumes a non-interactive session and sends a follow-up prompt. | Stable. Use for automation or CI-style continuations. |
codex exec resume <SESSION_ID> "Implement the plan" | Resumes a specific non-interactive run. | Stable. Accepts optional follow-up text. |
Interactive Slash Commands for Sessions
| Command | What it does | Notes |
|---|---|---|
/new | Starts a new conversation inside the current CLI session. | Official slash command. Does not clear the visible terminal first. |
/clear | Clears the terminal and starts a fresh chat. | Official slash command. Different from Ctrl+L, which only clears the screen. |
/resume | Opens a saved-session picker. | Official slash command. Use inside the TUI. |
/fork | Forks the current conversation into a new thread. | Official slash command. Keeps the original transcript intact. |
/side | Starts an ephemeral side conversation. | Official slash command. Useful for focused checks that should not disrupt the main thread. |
/compact | Summarizes earlier conversation to free context. | Official slash command. Use after long sessions. |
/copy | Copies the latest completed Codex output. | Official slash command. Ctrl+O is the shortcut. |
/exit | Exits the CLI. | Official slash command. Alias of /quit. |
/quit | Exits the CLI. | Official slash command. Alias of /exit. |
/logout | Signs out of Codex from inside the TUI. | Official slash command. |
/feedback | Opens feedback flow from inside the TUI. | Official slash command. |
Project and Workspace Commands
| Command | What it does | Notes |
|---|---|---|
codex --cd <path> | Starts Codex in a specific working directory. | Global stable flag. Also available as -C. |
codex --add-dir <path> | Grants access to an additional directory. | Global stable flag. Repeat for more paths. Prefer this over full sandbox bypass. |
codex --image screenshot.png "Fix this UI" | Attaches an image to the initial prompt. | Global stable flag. Also available as -i. |
codex app | Opens Codex Desktop from the terminal. | Stable on macOS and Windows. |
codex app <PATH> | Opens a workspace path in Codex Desktop. | Stable. macOS opens the path; Windows prints the path to open. |
codex completion zsh | Prints shell completions. | Stable. Supports bash, zsh, fish, powershell, and elvish. |
codex --no-alt-screen | Runs the TUI without alternate-screen mode. | Stable flag. Useful when terminal capture or scrollback matters. |
codex app --download-url | Prints the Codex Desktop download URL. | Listed in current official command reference. |
Interactive Workspace Slash Commands
| Command | What it does | Notes |
|---|---|---|
/mention src/file.ts | Attaches a file or folder to the conversation. | Official slash command. Helps Codex focus on specific paths. |
/init | Generates an AGENTS.md scaffold. | Official slash command. Review and edit before committing. |
/diff | Shows the Git diff, including untracked files. | Official slash command. Use before committing or asking for review. |
/status | Displays active model, approval policy, writable roots, token usage, and session details. | Official slash command. Good first diagnostic command. |
/debug-config | Prints config layer and policy diagnostics. | Official slash command. Use when settings do not behave as expected. |
/statusline | Configures TUI footer fields. | Official slash command. Persists to tui.status_line. |
/title | Configures terminal title fields. | Official slash command. Persists to tui.terminal_title. |
/keymap | Remaps TUI keyboard shortcuts. | Official slash command. Persists to tui.keymap. |
/agent | Creates, switches, lists, or manages delegated agents when the feature is available. | Official slash command. Feature-dependent. |
/ps | Lists background terminals or running tasks when background execution is available. | Official slash command. Feature-dependent. |
/stop | Stops running tasks when background execution is available. | Official slash command. Feature-dependent. |
Code Editing and Review Commands
| Command | What it does | Notes |
|---|---|---|
codex "Review this repo for bugs" | Starts an interactive review-oriented session. | Stable. This is a prompt, not a special subcommand. |
codex exec "Run the test suite and fix failures" | Runs Codex non-interactively until it finishes. | Stable. Good for scripted repair tasks. |
codex review | Runs a code review non-interactively. | Stable in current local CLI help. Prefer it for review-only automation. |
codex review --uncommitted | Reviews staged, unstaged, and untracked changes. | Stable in current local CLI help. |
codex review --base main | Reviews changes against a base branch. | Stable in current local CLI help. |
codex review --commit <SHA> | Reviews the changes introduced by one commit. | Stable in current local CLI help. |
codex exec --output-last-message result.md "Summarize the changes" | Writes the final assistant message to a file. | Stable. Useful for automation output. |
codex exec --output-schema schema.json "Return a JSON report" | Validates the final output against a JSON Schema. | Stable. Use when downstream tools need structured output. |
codex apply <TASK_ID> | Applies the latest diff from a Codex Cloud task. | Stable. Requires authentication and access to the task. Alias: codex a. |
/review | Reviews the current working tree. | Official slash command. Focuses on behavior changes, bugs, and missing tests. |
/diff | Shows current file changes. | Official slash command. Use after edits and before commits. |
codex exec review | Runs a code review through the codex exec command tree. | Stable in current local CLI help. Similar review flags are available under codex review. |
codex review --title "Title" | Sets an optional title in the review summary. | Stable in current local CLI help. |
Model, Reasoning, and Mode Controls
| Command | What it does | Notes |
|---|---|---|
codex --model <model> | Overrides the model for an interactive session. | Stable flag. Also available as -m. |
codex exec --model <model> "Task" | Overrides the model for a non-interactive run. | Stable flag. |
codex --profile <name> | Loads a named config profile. | Stable flag. Also available as -p. |
codex exec --profile <name> "Task" | Uses a profile for an automation run. | Stable flag. |
codex --oss | Uses the local open source provider. | Stable flag. Requires a running Ollama instance and OSS provider setup. |
codex features list | Lists feature flags and their effective state. | Stable command. |
codex features enable <feature> | Persistently enables a feature flag. | Stable command. Writes to config.toml. |
codex features disable <feature> | Persistently disables a feature flag. | Stable command. Writes to config.toml. |
/model | Chooses the active model and reasoning effort when available. | Official slash command. TUI-only. |
/fast on | Enables Fast mode for supported models. | Official slash command. Availability depends on sign-in method and model support. |
/fast off | Disables Fast mode. | Official slash command. |
/fast status | Shows current Fast mode state. | Official slash command. |
/plan | Switches to plan mode and optionally sends a planning prompt. | Official slash command. Unavailable while a task is already running. |
/personality | Changes communication style. | Official slash command. Supports friendly, pragmatic, and none when the active model supports it. |
/experimental | Toggles experimental features. | Official slash command. Restart may be required. |
Useful Model Config Keys
| Command | What it does | Notes |
|---|---|---|
model = "gpt-5.5" | Sets the default model. | Config key, not a command. Model availability changes by account and release. |
model_reasoning_effort = "medium" | Sets default reasoning effort. | Config key. Supported values include minimal, low, medium, high, and xhigh; model support varies. |
model_reasoning_summary = "auto" | Controls reasoning summary detail. | Config key. Supports auto, concise, detailed, and none. |
model_verbosity = "medium" | Sets GPT-5 Responses API verbosity. | Config key. Supports low, medium, and high. |
model_provider = "openai" | Selects the model provider. | Config key. Built-in provider IDs include openai, ollama, and lmstudio. |
oss_provider = "ollama" | Sets the default local provider for --oss. | Config key. Supports lmstudio and ollama. |
review_model = "<model>" | Sets the model used by /review. | Config key. Defaults to the active session model when unset. |
profiles.<name>.plan_mode_reasoning_effort = "high" | Sets reasoning for plan mode in a profile. | Config key. Useful for a planning-heavy profile. |
Permissions, Sandbox, and Safety
| Command | What it does | Notes |
|---|---|---|
codex --sandbox read-only | Runs with read-only sandbox policy. | Stable flag. Good for audit or explanation tasks. |
codex --sandbox workspace-write | Allows writes inside the workspace. | Stable flag. Common for local development. |
codex --sandbox danger-full-access | Disables Codex sandbox restrictions. | Stable flag but risky. Use only inside an isolated environment. |
codex --ask-for-approval untrusted | Controls when Codex asks before running commands. | Stable flag. |
codex --ask-for-approval on-request | Lets Codex ask when it needs higher-permission action. | Stable flag. Recommended for interactive local work. |
codex --ask-for-approval never | Prevents approval prompts. | Stable flag. Useful for non-interactive runs only when paired with a safe sandbox. |
codex --dangerously-bypass-approvals-and-sandbox | Runs without approvals or sandboxing. | Stable flag but dangerous. Same risk profile as --yolo. |
codex --yolo | Alias for bypassing approvals and sandboxing. | Stable alias, but unsafe outside a hardened container or VM. |
codex sandbox macos -- <COMMAND> | Runs a command under the macOS sandbox helper. | Experimental. Uses macOS Seatbelt. |
codex sandbox linux -- <COMMAND> | Runs a command under the Linux sandbox helper. | Experimental. Uses Landlock and seccomp. |
codex sandbox windows -- <COMMAND> | Runs a command under the Windows sandbox helper. | Experimental. |
codex execpolicy check --rules rules.json -- <COMMAND> | Tests execpolicy rules against a command. | Experimental preview. Emits JSON. |
/permissions | Changes approval behavior during an interactive session. | Official slash command. TUI-only. |
/sandbox-add-read-dir C:\absolute\path | Grants sandbox read access to another directory. | Official slash command, Windows only. |
Useful Safety Config Keys
| Command | What it does | Notes |
|---|---|---|
sandbox_mode = "workspace-write" | Persists the sandbox policy. | Config key. Values: read-only, workspace-write, danger-full-access. |
sandbox_workspace_write.writable_roots = ["/path"] | Adds writable roots in workspace-write mode. | Config key. Prefer narrow roots over full access. |
sandbox_workspace_write.network_access = true | Allows outbound network in workspace-write mode. | Config key. Keep disabled unless the task needs network access. |
approval_policy = "on-request" | Persists approval behavior. | Config key. on-failure is deprecated; use on-request or never. |
approval_policy.granular.sandbox_approval = true | Allows sandbox escalation prompts. | Config key. Part of granular approvals. |
history.persistence = "none" | Stops transcript persistence. | Config key. Useful for sensitive one-off work. |
hide_agent_reasoning = true | Hides reasoning events in TUI and codex exec output. | Config key. Does not change model behavior. |
Git and PR Workflows
| Command | What it does | Notes |
|---|---|---|
/diff | Shows all working tree changes Codex can see. | Official slash command. Includes untracked files. |
/review | Reviews current working tree changes. | Official slash command. Use before creating a PR. |
codex review | Runs a non-interactive code review from the shell. | Stable in current local CLI help. |
codex apply <TASK_ID> | Applies a Codex Cloud task diff locally. | Stable. Uses git apply and exits non-zero on conflicts. |
codex cloud | Opens an interactive cloud-task picker. | Experimental. Requires Codex Cloud access. |
codex cloud list --json | Lists recent cloud tasks as JSON. | Experimental. Useful for scripts. |
codex cloud list --env <ENV_ID> --limit 10 --json | Lists cloud tasks for one environment. | Experimental. Supports pagination with --cursor. |
codex cloud exec --env <ENV_ID> "Task" | Submits a cloud task directly. | Experimental. Requires a target Codex Cloud environment. |
codex cloud exec --env <ENV_ID> --branch <BRANCH> --attempts 2 "Task" | Submits a cloud task on a branch with multiple attempts. | Experimental. --attempts is best-of-N style. |
codex cloud status <TASK_ID> | Shows the status of a Codex Cloud task. | Experimental. |
codex cloud diff <TASK_ID> | Shows the unified diff for a cloud task. | Experimental. Add --attempt <N> when needed. |
codex cloud apply <TASK_ID> | Applies a cloud task diff locally. | Experimental. Add --attempt <N> when needed. |
Codex does not replace git. Keep normal Git commands in the workflow:
git status
git diff
codex
git add .
git commit -m "Fix parser edge case"Use Codex to inspect, edit, test, and review; use Git to stage, commit, branch, push, and open pull requests.
MCP, Integrations, and Tools
| Command | What it does | Notes |
|---|---|---|
codex mcp list | Lists configured MCP servers. | Experimental. Add --json for machine-readable output. |
codex mcp get <name> | Shows one MCP server configuration. | Experimental. Add --json for raw config. |
codex mcp add <name> -- <command...> | Adds a stdio MCP server launcher. | Experimental. The command after -- starts the server. |
codex mcp add <name> --url https://... | Adds a streamable HTTP MCP server. | Experimental. Mutually exclusive with a stdio command. |
codex mcp add <name> --env KEY=VALUE -- <command...> | Passes environment variables to a stdio MCP server. | Experimental. Repeat --env as needed. |
codex mcp add <name> --url https://... --bearer-token-env-var TOKEN_ENV | Uses an environment variable as an HTTP bearer token. | Experimental. Keep token values out of config. |
codex mcp login <name> | Starts OAuth login for a streamable HTTP MCP server. | Experimental. Only works when the server supports OAuth. |
codex mcp login <name> --scopes scope1,scope2 | Requests explicit OAuth scopes for an MCP server. | Experimental. Current local CLI help lists comma-separated scopes. |
codex mcp logout <name> | Removes stored OAuth credentials for an MCP server. | Experimental. |
codex mcp remove <name> | Deletes a stored MCP server definition. | Experimental. |
codex mcp-server | Runs Codex itself as an MCP server over stdio. | Experimental. Used when another MCP client consumes Codex. |
/mcp | Lists MCP tools available in the current TUI session. | Official slash command. Add verbose for server details. |
/apps | Browses apps/connectors and inserts them into a prompt. | Official slash command. App availability depends on installed connectors. |
/plugins | Browses installed and discoverable plugins. | Official slash command. Plugin availability depends on local setup. |
codex plugin marketplace add <source> | Adds a plugin marketplace. | Experimental. Accepts GitHub shorthand, Git URLs, SSH Git URLs, or local marketplace roots. |
codex plugin marketplace add <source> --ref <ref> | Adds a marketplace at a specific Git ref. | Experimental. Official docs list --ref for Git-backed sources. |
codex plugin marketplace add <source> --sparse <path> | Adds a marketplace from a sparse Git subdirectory. | Experimental. Useful for monorepo marketplace roots. |
codex plugin marketplace remove <marketplace-name> | Removes a configured plugin marketplace. | Experimental. |
codex plugin marketplace upgrade [marketplace-name] | Refreshes one or all Git-backed plugin marketplaces. | Experimental. |
MCP Config Keys
| Command | What it does | Notes |
|---|---|---|
mcp_servers.<id>.command = "node" | Defines a stdio MCP launcher command. | Config key. Use codex mcp add when possible. |
mcp_servers.<id>.args = ["server.js"] | Defines stdio MCP launcher arguments. | Config key. |
mcp_servers.<id>.env = { KEY = "VALUE" } | Sets environment variables for a stdio server. | Config key. Avoid storing secrets directly. |
mcp_servers.<id>.bearer_token_env_var = "TOKEN_ENV" | Reads an HTTP bearer token from the environment. | Config key. Better than hard-coding tokens. |
mcp_servers.<id>.enabled = false | Disables a server without deleting it. | Config key. |
mcp_servers.<id>.enabled_tools = ["tool_name"] | Allows only selected tools. | Config key. Useful for least-privilege tool access. |
mcp_servers.<id>.disabled_tools = ["tool_name"] | Blocks selected tools. | Config key. Applied after enabled_tools. |
CLI Flags
| Command | What it does | Notes |
|---|---|---|
--add-dir <path> | Grants access to another directory. | Global flag. Repeatable. |
--ask-for-approval, -a <policy> | Sets approval behavior. | Values: untrusted, on-request, never. on-failure is deprecated. |
--cd, -C <path> | Sets working directory before the task starts. | Global flag. |
--config, -c key=value | Overrides config for one invocation. | Values parse as TOML when possible; otherwise Codex treats the value as a literal string. |
--dangerously-bypass-approvals-and-sandbox | Disables approvals and sandboxing. | Dangerous. Use only inside an external sandbox. |
--yolo | Alias for bypassing approvals and sandboxing. | Dangerous alias. |
--disable <feature> | Disables a feature flag for this run. | Repeatable. Equivalent to -c features.<name>=false. |
--enable <feature> | Enables a feature flag for this run. | Repeatable. Equivalent to -c features.<name>=true. |
--image, -i <path[,path...]> | Attaches images to the first prompt. | Repeatable. |
--help, -h | Prints help. | Global flag. Use subcommand help for narrower output. |
--version, -V | Prints installed Codex CLI version. | Global flag. Useful when checking docs against local behavior. |
--model, -m <model> | Overrides the configured model. | Global flag. |
--no-alt-screen | Disables alternate-screen TUI mode. | Global flag. |
--oss | Uses a local open source provider. | Requires local provider setup. |
--local-provider <provider> | Selects a local OSS provider. | Current local help lists lmstudio and ollama. Usually paired with --oss. |
--profile, -p <name> | Loads a config profile. | Global flag. |
--remote <ws://host:port> | Connects TUI to a remote app server. | Supported for codex, codex resume, and codex fork. |
--remote-auth-token-env <ENV_VAR> | Sends a bearer token for remote TUI auth. | Requires --remote. Token rules differ for ws:// and wss://. |
--sandbox, -s <mode> | Sets sandbox policy. | Values: read-only, workspace-write, danger-full-access. |
--search | Enables live web search. | Sets web_search = "live" instead of default cached mode. |
Non-Interactive Mode
| Command | What it does | Notes |
|---|---|---|
codex exec "Task" | Runs Codex without opening the TUI. | Stable. Alias: codex e. |
codex exec - | Reads the prompt from stdin. | Stable. Good for generated prompts. |
codex exec review --base main | Runs a non-interactive review through codex exec. | Stable in current local CLI help. Supports review flags such as --base, --commit, and --uncommitted. |
codex exec --json "Task" | Prints newline-delimited JSON events. | Stable. --experimental-json remains an alias. |
codex exec --ephemeral "Task" | Avoids persisting session rollout files. | Stable. Useful for short-lived automation. |
codex exec --skip-git-repo-check "Task" | Allows running outside a Git repository. | Stable. Use for one-off directories. |
codex exec --ignore-user-config "Task" | Ignores $CODEX_HOME/config.toml. | Stable. Authentication still uses CODEX_HOME. |
codex exec --ignore-rules "Task" | Skips user and project execpolicy .rules files. | Stable. Use only when policy bypass is intentional. |
codex exec --color never "Task" | Controls ANSI color output. | Stable. Values: always, never, auto. |
codex exec --output-last-message out.md "Task" | Writes the final response to a file. | Stable. Useful in CI. |
codex exec --output-schema schema.json "Task" | Validates final response shape. | Stable. Schema file must exist. |
Environment Variables
| Command | What it does | Notes |
|---|---|---|
OPENAI_API_KEY | Holds an OpenAI API key for API-key authentication flows. | Environment variable. Pipe it to codex login --with-api-key; avoid committing it. |
CODEX_HOME | Changes where Codex stores config, auth, logs, and sessions. | Environment variable. Defaults to ~/.codex. |
CODEX_CA_CERTIFICATE | Points Codex at a custom CA bundle. | Environment variable. Falls back to SSL_CERT_FILE when unset. |
SSL_CERT_FILE | Fallback custom CA bundle path. | Environment variable used when CODEX_CA_CERTIFICATE is unset. |
RUST_LOG | Controls Rust logging verbosity. | Environment variable. Mentioned in the open-source repo docs; useful for debugging. |
CODEX_REMOTE_AUTH_TOKEN | Example bearer-token variable for remote TUI auth. | Environment variable name is arbitrary; pass it through --remote-auth-token-env. |
mcp_servers.<id>.bearer_token_env_var target | Supplies a bearer token to an MCP HTTP server. | Environment variable name is configured in config.toml. |
Custom provider env_key target | Supplies a provider-specific API key. | Environment variable name is chosen in model_providers.<id>.env_key. |
Custom Commands and Automation
Codex supports automation mainly through codex exec, MCP, plugins, config profiles, hooks, and AGENTS.md. Do not treat prompts, aliases, or local shell scripts as official Codex commands unless the Codex docs list them.
| Command | What it does | Notes |
|---|---|---|
codex exec "Task" | Runs a one-shot automation task. | Stable. Best starting point for scripts and CI. |
codex exec --json --output-last-message out.md "Task" | Streams machine-readable progress and saves final prose. | Stable. Practical CI pattern. |
codex features enable <feature> | Turns on a feature persistently. | Stable command, but individual feature maturity varies. |
codex plugin marketplace add <source> | Adds plugin sources. | Experimental. Official but not stable. |
codex mcp add <name> -- <command...> | Adds tool integrations through MCP. | Experimental. Official but may change. |
/init | Creates an AGENTS.md instruction scaffold. | Official slash command. Project-specific instructions are not commands. |
Hooks in config.toml | Runs lifecycle hooks. | Config feature, not a CLI command. Keep hook scripts small and auditable. |
Community, Experimental, and Deprecated Items
| Command | What it does | Notes |
|---|---|---|
codex app-server | Runs the Codex app server for local development or debugging. | Official experimental command. May change without notice. |
codex cloud | Works with Codex Cloud tasks from the terminal. | Official experimental command. Requires Codex Cloud access. |
codex execpolicy | Tests execpolicy rules. | Official experimental preview. |
codex mcp | Manages MCP server entries. | Official experimental command. |
codex mcp-server | Runs Codex as an MCP server. | Official experimental command. |
codex sandbox | Runs commands in Codex-provided sandboxes. | Official experimental command. |
codex plugin marketplace | Manages plugin marketplace sources. | Official experimental command. |
/approvals | Legacy alias for approval controls. | Still works according to docs, but no longer appears in the slash popup. Prefer /permissions. |
/clean | Alias for /stop. | Still available according to docs. Prefer /stop. |
--full-auto | Compatibility shortcut for sandboxed automatic execution. | Official command reference marks it deprecated; current local help may describe it as a convenience alias. Prefer explicit --sandbox and approval flags in scripts. |
--experimental-json | Alias for --json in codex exec. | Keep new scripts on --json. |
codex --upgrade | Older help-center update command. | Treat as outdated unless confirmed in the installed CLI. Current command reference documents codex update. |
codex debug seatbelt | Legacy alias for sandbox testing. | Mentioned in repository docs as a legacy alias. Prefer codex sandbox macos. |
codex debug landlock | Legacy alias for sandbox testing. | Mentioned in repository docs as a legacy alias. Prefer codex sandbox linux. |
Real Workflows
Start a New Project
mkdir my-app
cd my-app
git init
codex --sandbox workspace-write --ask-for-approval on-request "Create a small starter app with tests"Use this when Codex should create files but still ask before risky commands.
Explain an Existing Repository
cd existing-repo
codex --sandbox read-only "Explain the architecture and identify the main entry points"Use read-only mode when you want analysis without edits.
Fix a Failing Test
cd repo
codex exec --sandbox workspace-write --ask-for-approval never "Run the relevant tests, fix the failure, and summarize the patch"Use this for focused repair work in a trusted repository; keep the sandbox on.
Review a Pull Request Locally
git fetch origin
git checkout feature-branch
codex --sandbox read-only "Review the working tree for bugs, regressions, and missing tests"Use Codex as a reviewer after checking out the branch.
Run a Non-Interactive Review
codex review --base mainUse this when you want a review report from the shell without opening the TUI.
Review Changes Inside the TUI
/diff
/reviewUse this after Codex edits files and before staging a commit.
Refactor a Module
codex --sandbox workspace-write --ask-for-approval on-request "Refactor src/auth without changing public behavior. Run targeted tests."Use this when edits are expected but command execution should remain visible.
Resume a Previous Task
codex resume --lastUse this when the prior interactive conversation already contains the plan and context.
Resume a Previous Non-Interactive Task
codex exec resume --last "Continue from the previous failure and finish the test fix"Use this when an automation run stopped before the work was complete.
Fork a Session Before Trying a Riskier Approach
codex fork --lastUse this when one solution path should remain intact while another is explored.
Run Codex in Headless Mode
codex exec --json --output-last-message codex-result.md "Audit this package and report actionable issues"Use this in CI or scripted environments that need structured progress and a final summary.
Run Outside a Git Repository
codex exec --skip-git-repo-check "Organize these loose scripts and explain the changes"Use this only for one-off directories where Git history is not available.
Use a Specific Model for One Run
codex exec --model gpt-5.5 "Find the safest way to simplify this module"Use a model override when a task needs a different cost, speed, or reasoning profile than your default.
Use a Profile for High-Control Work
codex --profile cautious --sandbox read-only "Audit the payment code for risky changes"Use profiles to keep repeatable defaults for different work styles.
Keep Context Lean During Long Work
/status
/compact
/statusUse /compact after long exchanges so the session keeps key details without carrying every turn.
Add an MCP Server
codex mcp add docs -- node ./mcp-docs-server.js
codex mcp listUse this when Codex needs a local tool or documentation server through MCP.
Add an HTTP MCP Server with a Token
export DOCS_MCP_TOKEN="..."
codex mcp add docs-http --url https://example.com/mcp --bearer-token-env-var DOCS_MCP_TOKENUse an environment variable for secrets instead of hard-coding tokens in config.
Check Sandbox Behavior
codex sandbox linux -- npm testUse this when you need to reproduce how a command behaves under Codex’s sandbox on Linux.
Apply a Codex Cloud Patch
codex cloud list --json
codex apply <TASK_ID>
git diffUse this when a cloud task produced a patch that should be tested locally.
Avoid Full Access When One Extra Directory Is Needed
codex --sandbox workspace-write --add-dir ../shared "Update this project and the shared package together"Use --add-dir instead of disabling the sandbox.
Run With Temporary Output Only
codex exec --ephemeral "Inspect this generated output and summarize issues"Use ephemeral mode when you do not want rollout files saved for a short task.
FAQs
What is Codex CLI?
Codex CLI is OpenAI’s terminal-based coding agent. It runs locally, reads and edits files in your workspace, runs commands according to your sandbox and approval settings, and can continue work across saved sessions.
How do Codex commands differ from prompts?
Commands change Codex behavior or launch a Codex mode. Prompts tell the agent what work to do. For example, codex exec is a command; "Fix the failing parser test" is a prompt.
Does Codex support slash commands?
Yes. Current Codex CLI docs list many slash commands, including /status, /model, /permissions, /compact, /diff, /review, /resume, and /new. They work inside the interactive TUI, not directly from the shell.
How do I run Codex non-interactively?
Use codex exec "Task" or its alias codex e "Task". Add --json for newline-delimited JSON events, --output-last-message to save the final response, and --sandbox workspace-write when Codex needs to edit files.
How do I control permissions or sandboxing?
Use --sandbox read-only, --sandbox workspace-write, or --sandbox danger-full-access for one run. Use --ask-for-approval on-request or --ask-for-approval never to control approval prompts. Persist defaults with sandbox_mode and approval_policy in ~/.codex/config.toml.
How do I resume a Codex session?
Use codex resume for an interactive picker, codex resume --last for the most recent session, or codex resume <SESSION_ID> for a specific session. For non-interactive runs, use codex exec resume --last "Follow-up task".
Can Codex work with GitHub or PRs?
Codex can review local working tree changes with /review, show diffs with /diff, and apply Codex Cloud task patches with codex apply <TASK_ID>. Normal Git and GitHub operations such as branching, staging, committing, pushing, and opening PRs still belong to Git, GitHub CLI, or GitHub integrations.
What is the difference between Codex and Claude Code?
Codex CLI is OpenAI’s coding agent and uses OpenAI authentication, models, configuration, sandboxing, MCP support, and TUI commands. Claude Code is Anthropic’s separate coding agent with its own command set, permission model, slash commands, configuration, and model family. Commands from one tool should not be assumed to exist in the other.
Is --full-auto still the best way to run autonomous edits?
Not for new scripts. The official command reference marks --full-auto deprecated, while the current local CLI help may still describe it as a convenience alias. Explicit --sandbox and approval flags are easier to audit and less likely to be misunderstood.
Is codex --upgrade current?
The older OpenAI Help Center article mentions codex --upgrade, but the current Codex CLI command reference documents codex update. Treat codex --upgrade as outdated unless codex --help on your installed version confirms it.
Where is Codex configuration stored?
Codex defaults to ~/.codex/config.toml, with logs, auth, and sessions under CODEX_HOME when that environment variable is set. Credentials are cached in ~/.codex/auth.json or an OS credential store depending on cli_auth_credentials_store.
Related Resources
- Codex CLI reference: The official source for Codex.
- OpenAI Codex GitHub repository: The official source repository for Codex CLI.
- Best Agent Skills: 10 Best Free Agent Skills for Claude Code & AI Workflows.
- Claude Code Slash Commands Cheatsheet: The most complete, verified reference for every Claude Code slash command.
- AI Coding Agents: 7 Best CLI AI Coding Agents.
- Best Web Dev Tools: 10 Best Free AI Tools for Frontend Developers
