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: June 15, 2026
Table Of Contents
Quick Classification
| Type | Where to use it |
|---|---|
| CLI command | Type in your shell, such as codex exec "Fix failing tests". |
| Slash command | Type inside the interactive Codex TUI, such as /status. |
| TUI shortcut | Type inside the TUI composer, such as @. |
| CLI flag | Add after codex or a subcommand, such as --model. |
| Config key | Save in ~/.codex/config.toml. |
| Environment variable | Set in the shell before running Codex. |
| Integration API | Use through app-server or another integration client. |
CLI Commands
Use these from a terminal prompt before or instead of opening the interactive TUI.
| Command | Use |
|---|---|
npm install -g @openai/codex | Install Codex CLI with npm. |
brew install --cask codex | Install Codex CLI with Homebrew on macOS. |
codex | Open the interactive TUI in the current project. |
codex "Explain this codebase" | Open the TUI with an initial prompt. |
codex login | Start the default ChatGPT sign-in flow. |
codex login --device-auth | Use device-code auth for headless or remote environments. |
printenv OPENAI_API_KEY | codex login --with-api-key | Sign in with an API key from stdin. |
codex login status | Check the active authentication mode. |
codex logout | Remove stored Codex credentials. |
codex update | Apply an update when the installed build supports self-update. |
codex resume | Open a picker for saved sessions. |
codex resume --last | Resume the most recent saved session. |
codex resume <SESSION_ID> | Resume a specific saved session. |
codex fork | Fork a previous session into a new thread. |
codex archive | Archive a saved session. |
codex unarchive | Restore an archived session. |
codex delete | Permanently delete a saved session after confirmation. |
codex exec "Task" | Run a non-interactive task. |
codex exec - | Read the prompt from stdin. |
codex exec resume --last "Task" | Continue the last non-interactive run. |
codex review | Run a non-interactive code review. |
codex apply <TASK_ID> | Apply the latest diff from a Codex Cloud task. |
codex doctor | Create a local diagnostic report. |
codex app | Open Codex Desktop from the terminal. |
codex app <PATH> | Open a workspace path in Codex Desktop. |
codex app --download-url | Print the Codex Desktop download URL. |
codex completion zsh | Print shell completions for a supported shell. |
Cloud, MCP, and Plugin CLI Commands
| Command | Use |
|---|---|
codex cloud | Open a Codex Cloud task picker. |
codex cloud list --json | List recent cloud tasks as JSON. |
codex cloud status <TASK_ID> | Show a cloud task status. |
codex cloud diff <TASK_ID> | Show a cloud task diff. |
codex cloud apply <TASK_ID> | Apply a cloud task diff locally. |
codex mcp list | List configured MCP servers. |
codex mcp get <name> | Show one MCP server configuration. |
codex mcp add <name> -- <command...> | Add a stdio MCP server. |
codex mcp add <name> --url https://... | Add a streamable HTTP MCP server. |
codex mcp login <name> | Start OAuth login for an MCP server. |
codex mcp logout <name> | Remove stored MCP OAuth credentials. |
codex mcp remove <name> | Delete an MCP server definition. |
codex mcp-server | Run Codex itself as an MCP server. |
codex plugin list --json | List installed plugins as JSON. |
codex plugin add --json | Add a plugin with structured output. |
codex plugin remove --json | Remove a plugin with structured output. |
codex plugin marketplace list --json | List marketplace sources as JSON. |
codex plugin marketplace add <source> | Add a plugin marketplace. |
codex plugin marketplace remove <name> | Remove a plugin marketplace. |
codex plugin marketplace upgrade [name] | Refresh Git-backed plugin marketplaces. |
TUI Shortcuts
These are typed inside the TUI composer but are not slash commands.
| Shortcut | Use |
|---|---|
@ | Open the unified mentions menu for files, plugins, and skills. |
Slash Commands
Use these only after codex opens the interactive TUI.
| Slash command | Use |
|---|---|
/status | Check model, approval mode, roots, token use, and session details. |
/usage | View daily, weekly, and cumulative account token activity. |
/new | Start a new conversation. |
/clear | Clear the terminal and start fresh. |
/resume | Open the saved-session picker. |
/fork | Fork the current conversation. |
/archive | Archive the current session. |
/delete | Permanently delete the current session after confirmation. |
/side | Start a temporary side conversation. |
/compact | Summarize earlier turns to reduce context use. |
/copy | Copy the latest completed response. |
/import | Import selected data from Claude Code. |
/diff | Show current working tree changes. |
/review | Review current changes for bugs and regressions. |
/permissions | Change approval behavior. |
/sandbox-add-read-dir C:\absolute\path | Grant sandbox read access to another Windows directory. |
/mention src/file.ts | Attach a file or folder to the conversation. |
/init | Create an AGENTS.md scaffold. |
/model | Choose model and reasoning effort. |
/fast on, /fast off, /fast status | Control Fast mode when supported. |
/plan | Switch to plan mode. |
/goal | Set or view a long-running goal. |
/personality | Change response style when supported. |
/experimental | Toggle experimental features. |
/mcp | List MCP tools in the current session. |
/apps | Browse apps and connectors. |
/plugins | Browse installed and discoverable plugins. |
/app | Hand off the current CLI thread to Codex Desktop. |
/statusline | Configure TUI footer fields. |
/title | Configure terminal title fields. |
/keymap | Remap TUI keyboard shortcuts. |
/agent | Manage delegated agents when available. |
/ps | List background terminals or running tasks. |
/stop | Stop a running task. |
/exit or /quit | Exit the TUI. |
/logout | Sign out from inside the TUI. |
/feedback | Open the feedback flow. |
/approvals | Legacy alias. Prefer /permissions. |
/clean | Alias for /stop. |
CLI Flags
Add these to codex, codex exec, or another subcommand when the command supports them.
| Flag | Use |
|---|---|
--add-dir <path> | Grant access to another directory. |
--ask-for-approval, -a <policy> | Set approval behavior for one run. |
--cd, -C <path> | Set the working directory. |
--config, -c key=value | Override config for one invocation. |
--dangerously-bypass-approvals-and-sandbox | Disable approvals and sandboxing. |
--yolo | Alias for bypassing approvals and sandboxing. |
--disable <feature> | Disable a feature flag for one run. |
--enable <feature> | Enable a feature flag for one run. |
--image, -i <path> | Attach an image to the first prompt. |
--help, -h | Print help. |
--version, -V | Print the installed CLI version. |
--model, -m <model> | Override the configured model. |
--no-alt-screen | Disable alternate-screen TUI mode. |
--oss | Use a local open source provider. |
--local-provider <provider> | Select a local OSS provider. |
--profile, -p <name> | Load a config profile. |
--remote <ws://host:port> | Connect the TUI to a remote app server. |
--remote-auth-token-env <ENV_VAR> | Send a bearer token for remote TUI auth. |
--sandbox, -s <mode> | Set sandbox policy. |
--search | Enable live web search. |
--json | Print newline-delimited JSON events for codex exec. |
--ephemeral | Avoid saving session rollout files. |
--skip-git-repo-check | Run outside a Git repository. |
--ignore-user-config | Ignore user config for one run. |
--ignore-rules | Skip user and project execpolicy rules. |
--color never | Control ANSI color output. |
--output-last-message out.md | Save the final response to a file. |
--output-schema schema.json | Validate the final response against a JSON Schema. |
--full-auto | Deprecated shortcut. Prefer explicit sandbox and approval flags. |
--experimental-json | Legacy alias for --json. |
Config Keys
Put these in ~/.codex/config.toml when you want persistent defaults.
| Config key | Use |
|---|---|
model = "gpt-5.5" | Set the default model. |
model_reasoning_effort = "medium" | Set default reasoning effort. |
model_reasoning_summary = "auto" | Control reasoning summary detail. |
model_verbosity = "medium" | Set GPT-5 Responses API verbosity. |
model_provider = "openai" | Select the model provider. |
oss_provider = "ollama" | Set the provider used by --oss. |
review_model = "<model>" | Set the model used by /review. |
sandbox_mode = "workspace-write" | Persist the sandbox policy. |
sandbox_workspace_write.writable_roots = ["/path"] | Add writable roots in workspace-write mode. |
sandbox_workspace_write.network_access = true | Allow outbound network in workspace-write mode. |
approval_policy = "on-request" | Persist approval behavior. |
history.persistence = "none" | Stop transcript persistence. |
hide_agent_reasoning = true | Hide reasoning events in TUI and exec output. |
mcp_servers.<id>.command = "node" | Define a stdio MCP launcher command. |
mcp_servers.<id>.args = ["server.js"] | Define stdio MCP launcher arguments. |
mcp_servers.<id>.env = { KEY = "VALUE" } | Set environment variables for a stdio MCP server. |
mcp_servers.<id>.bearer_token_env_var = "TOKEN_ENV" | Read an HTTP bearer token from an environment variable. |
mcp_servers.<id>.enabled = false | Disable a server without deleting it. |
mcp_servers.<id>.enabled_tools = ["tool_name"] | Allow only selected MCP tools. |
mcp_servers.<id>.disabled_tools = ["tool_name"] | Block selected MCP tools. |
Hooks in config.toml | Run lifecycle hooks. |
Environment Variables
| Variable | Use |
|---|---|
OPENAI_API_KEY | Store an OpenAI API key for API-key auth flows. |
CODEX_API_KEY | Register remote execution setup for approved OpenAI hosts. |
CODEX_HOME | Change where Codex stores config, auth, logs, and sessions. |
CODEX_NON_INTERACTIVE=1 | Run supported install scripts without prompts. |
CODEX_CA_CERTIFICATE | Point Codex at a custom CA bundle. |
SSL_CERT_FILE | Fallback custom CA bundle path. |
RUST_LOG | Control Rust logging verbosity. |
CODEX_REMOTE_AUTH_TOKEN | Example bearer-token variable for remote TUI auth. |
Custom provider env_key | Supply a provider-specific API key. |
Experimental CLI Commands
| Command | Use |
|---|---|
codex app-server | Run the Codex app server for local integration work. |
codex app-server --stdio | Launch app-server in stdio mode. |
codex remote-control | Start or manage a remotely controllable app-server. |
codex execpolicy | Test execpolicy rules. |
codex sandbox macos -- <COMMAND> | Run a command under the macOS sandbox helper. |
codex sandbox linux -- <COMMAND> | Run a command under the Linux sandbox helper. |
codex sandbox windows -- <COMMAND> | Run a command under the Windows sandbox helper. |
codex sandbox setup --elevated | Provision supported Windows sandbox requirements. |
codex --upgrade | Older update command. Prefer codex update. |
codex debug seatbelt | Legacy alias. Prefer codex sandbox macos. |
codex debug landlock | Legacy alias. Prefer codex sandbox linux. |
App Server Integration APIs
| Integration API | Use |
|---|---|
app-server thread/delete | Delete a thread through app-server integration. |
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.
Set a Long-Running Goal
codex features enable goals
codex
/goal ship the parser refactor without changing public behaviorUse this when a long task needs a persistent target that Codex can track across the session. The feature is experimental and requires features.goals.
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 and recent changelog entries list many slash commands, including /status, /usage, /model, /permissions, /compact, /diff, /review, /resume, /new, /import, /delete, and /goal. They work inside the interactive TUI, not directly from the shell. Some slash commands, including /goal, are experimental or feature-gated.
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. Recent releases also added encrypted local storage for CLI and MCP OAuth credentials.
Command Verification Notes
Use the official OpenAI Codex CLI documentation as the primary source for command availability. Local codex --help output is useful for checking the installed version, but it can lag behind the latest CLI release or differ from Codex Desktop behavior.
When the official docs and local help differ, mark the command as official but version-dependent, then include the feature flag, platform, or release condition that controls access.
Related Resources
- Claude Code Slash Commands Cheatsheet: The most complete, verified reference for every Claude Code slash command.
- OpenAI Codex CLI reference: The official source for Codex.
- OpenAI Codex CLI GitHub repository: The official source repository for Codex CLI.
- Best Agent Skills: 10 Best Free Agent Skills for Claude Code & AI Workflows.
- AI Coding Agents: 7 Best CLI AI Coding Agents.
- Best Web Dev Tools: 10 Best Free AI Tools for Frontend Developers
