Complete OpenAI Codex CLI commands reference — 114 commands across 16 categories. Quick reference cheat sheet for Cross-platform.
Codex CLI is OpenAI's terminal coding agent, and this page is its command-line surface: the global flags that shape a session, the subcommands, and the per-command options as the current release prints them in --help. The slash commands and prompt conventions used inside the TUI live on the prompts page; this one is about how you start Codex and how you run it unattended.
Looking for slash commands? They moved to the new Codex CLI prompt commands reference.
| Shortcut | Action |
|---|---|
| --add-dir | Grant additional directories write access alongside the main workspace. Repeat for multiple |
| --ask-for-approval, -a | Control when Codex pauses for human approval before running a command |
| --cd, -C | Set the working directory for the agent before it starts processing your request |
| --config, -c | Override configuration values. Values parse as TOML if possible; otherwise the literal string |
| --dangerously-bypass-approvals-and-sandbox, --yolo | Run every command without approvals or sandboxing. Only use inside an externally hardened |
| --dangerously-bypass-hook-trust | Run enabled hooks without requiring persisted hook trust for this invocation. Intended only |
| --disable | Force-disable a feature flag (translates to -c features.<name>=false). Repeatable |
| --enable | Force-enable a feature flag (translates to -c features.<name>=true). Repeatable |
| --image, -i | Attach one or more image files to the initial prompt. Separate multiple paths with commas |
| --local-provider | Choose the local provider used with --oss, overriding oss_provider for this run |
| --model, -m | Override the model set in configuration (for example gpt-5.4) |
| --no-alt-screen | Disable alternate screen mode for the TUI (overrides tui.alternate_screen for this run) |
| --oss | Use a local open source model provider. Codex uses --local-provider, your configured |
| --profile, -p | Layer $CODEX_HOME/profile-name.config.toml on top of the base user config |
| --remote | Connect to a remote app-server endpoint over WebSocket or a Unix socket. Supported for codex |
| --remote-auth-token-env | Read a bearer token from this environment variable and send it when connecting with --remote. |
| --sandbox, -s | Select the sandbox policy for model-generated shell commands |
| --search | Enable live web search (sets web_search = "live" instead of the default "cached") |
| --strict-config | Error when config.toml contains fields this Codex version does not recognize. Supported |
| PROMPT | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled |
| Shortcut | Action |
|---|---|
| codex | Launch the terminal UI. Accepts the global flags above plus an optional prompt or image |
| codex app | Launch the ChatGPT desktop app on macOS or Windows. On macOS, Codex can open a workspace path |
| codex app-server | Launch the Codex app server for local development or debugging over stdio, WebSocket, or a Unix |
| codex apply | Apply the latest diff generated by a Codex cloud chat to your local working tree. Alias: codex |
| codex archive | Archive a saved interactive session by session ID or session name |
| codex cloud | Browse or execute Codex cloud chats from the terminal without opening the TUI. Alias: codex |
| codex completion | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell |
| codex debug app-server send-message-v2 | Debug app-server by sending a single V2 message through the built-in test client |
| codex debug models | Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog |
| codex debug prompt-input | Render the model-visible prompt input list as JSON, optionally with a prompt and images |
| codex delete | Permanently delete a saved interactive session by session ID or session name |
| codex doctor | Generate a diagnostic report for local installation, config, auth, runtime, Git, terminal |
| codex exec | Run Codex non-interactively. Alias: codex e. Stream results to stdout or JSONL and optionally |
| codex execpolicy | Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked |
| codex features | List feature flags and persistently enable or disable them in config.toml |
| codex fork | Fork a previous interactive session into a new chat, preserving the original transcript |
| codex login | Authenticate Codex using ChatGPT OAuth, device auth, an API key, or an access token piped over |
| codex logout | Remove stored authentication credentials |
| codex mcp | Manage Model Context Protocol servers (list, add, remove, authenticate) |
| codex mcp-server | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex |
| codex plugin | Install, list, and remove plugins from configured marketplace sources |
| codex plugin marketplace | Add, list, upgrade, or remove plugin marketplaces from Git or local sources |
| codex remote-control | Run or manage remote control for the local app-server, or create a short-lived pairing code |
| codex resume | Continue a previous interactive session by ID or resume the most recent chat |
| codex review | Run a non-interactive review of uncommitted changes, a base branch diff, a commit, or custom |
| codex sandbox | Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes |
| codex unarchive | Restore an archived interactive session by session ID or session name |
| codex update | Check for and apply a Codex CLI update when the installed release supports self-update |
| Shortcut | Action |
|---|---|
| --analytics-default-enabled | Defaults analytics to enabled for first-party app-server clients unless the user opts out |
| --listen | Transport listener URL. Use stdio:// for JSONL, ws://IP:PORT for a TCP WebSocket endpoint |
| --stdio | Use stdio transport. Equivalent to --listen stdio:// and mutually exclusive with --listen |
| --ws-audience | Expected aud claim for signed bearer tokens. Requires --ws-auth signed-bearer-token |
| --ws-auth | Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled |
| --ws-issuer | Expected iss claim for signed bearer tokens. Requires --ws-auth signed-bearer-token |
| --ws-max-clock-skew-seconds | Clock skew allowance when validating signed bearer token exp and nbf claims. Requires --ws-auth |
| --ws-shared-secret-file | File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required |
| --ws-token-file | File containing the shared capability token. Use with --ws-auth capability-token unless you |
| --ws-token-sha256 | Expected SHA-256 digest for capability-token authentication. Use instead of --ws-token-file |
| Shortcut | Action |
|---|---|
| --download-url | Advanced override for the ChatGPT desktop app installer URL used during install |
| PATH | Workspace path for the ChatGPT desktop app. On macOS, Codex opens this path; on Windows, Codex |
| Shortcut | Action |
|---|---|
| --base | Review changes against the specified base branch |
| --commit | Review the changes introduced by the specified commit |
| --title | Set the commit title shown in the review summary. Requires --commit |
| --uncommitted | Review staged, unstaged, and untracked changes |
| Shortcut | Action |
|---|---|
| --attempts | Number of assistant attempts (best-of-N) Codex cloud should run |
| --env | Target Codex cloud environment identifier (required). Use codex cloud to list options |
| QUERY | Task prompt. If omitted, Codex prompts interactively for details |
| Shortcut | Action |
|---|---|
| --cursor | Pagination cursor returned by a previous request |
| --json | Emit machine-readable JSON instead of plain text |
| --limit | Maximum number of tasks to return |
| Shortcut | Action |
|---|---|
| --all | Expand long lists in the detailed human-readable report |
| --ascii | Use ASCII status labels and separators in human-readable output |
| --no-color | Disable ANSI color in human-readable output |
| --summary | Show grouped check rows and the final count summary only |
| Shortcut | Action |
|---|---|
| --color | Control ANSI color in stdout |
| --ephemeral | Run without persisting session rollout files to disk |
| --full-auto | Deprecated compatibility flag. Prefer --sandbox workspace-write; Codex prints a warning when |
| --ignore-rules | Do not load user or project execpolicy .rules files for this run |
| --ignore-user-config | Do not load $CODEX_HOME/config.toml. Authentication still uses CODEX_HOME |
| --json, --experimental-json | Print newline-delimited JSON events instead of formatted text |
| --output-last-message, -o | Write the assistant's final message to a file. Useful for downstream scripting |
| --output-schema | JSON Schema file describing the expected final response shape. Codex validates tool output |
| --skip-git-repo-check | Allow running outside a Git repository (useful for one-off directories) |
| -c, --config | Inline configuration override for the non-interactive run (repeatable) |
| --last | Resume the most recent chat from the current working directory |
| SESSION_ID | Resume the specified session. Omit and use --last to continue the most recent session |
| Shortcut | Action |
|---|---|
| --pretty | Pretty-print the JSON result |
| --rules, -r | Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across |
| COMMAND... | Command to be checked against the specified policies |
| Shortcut | Action |
|---|---|
| --device-auth | Use OAuth device code flow instead of launching a browser window |
| --with-access-token | Read an access token from stdin |
| --with-api-key | Read an API key from stdin (for example printenv OPENAI_API_KEY | codex login --with-api-key) |
| Shortcut | Action |
|---|---|
| list | List configured MCP servers. Add --json for machine-readable output |
| --bearer-token-env-var | Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP |
| --env KEY=VALUE | Environment variable assignments applied when launching a stdio server |
| --oauth-client-id | OAuth client identifier for a streamable HTTP MCP server. Requires --url |
| --oauth-resource | OAuth resource parameter to include during login for a streamable HTTP MCP server. Requires |
| --url | Register a streamable HTTP server instead of stdio. Mutually exclusive with COMMAND |
| Shortcut | Action |
|---|---|
| --allow-unix-socket | Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat |
| --include-managed-config | Include managed requirements while resolving an explicit permissions profile. Requires |
| --log-denials | Capture macOS sandbox denials with log stream while the command runs and print them after exit |
| --permission-profile, -P | Apply a named permissions profile from the active configuration stack |
| Shortcut | Action |
|---|---|
| chatgpt.addToThread | Add selected text range as context for the current chat |
| chatgpt.addFileToThread | Add the entire file as context for the current chat |
| chatgpt.newChat | Create a new chat |
| chatgpt.newCodexPanel | Create a new Codex panel |
| chatgpt.openCommandMenu | Open the Codex command menu |
| chatgpt.openSidebar | Open the Codex sidebar panel |
| Shortcut | Action |
|---|---|
| Esc | Stop response |
| Up / Down | Browse history |
| Tab | Autocomplete |
| Ctrl + C | Cancel |
| Ctrl + L | Clear screen |
| Ctrl + D | Exit |
codex alone opens the terminal UI in the current directory; give it a prompt as an argument to skip the first question. --model, -m overrides the configured model for one run, --cd, -C sets the working directory, and --add-dir grants write access to a second directory such as a shared library next to the app. --profile, -p layers a named config file over the base one, which is how a team keeps separate settings for reviewing versus generating. --image, -i attaches screenshots to the first prompt, useful for "make it look like this".
--ask-for-approval, -a sets when Codex stops for confirmation before running a command, and --permission-profile, -P applies a named sandbox profile from the configuration. --dangerously-bypass-approvals-and-sandbox, --yolo removes both — the flag name is long on purpose, and it belongs only inside a container or a throwaway VM. codex execpolicy evaluates a rule file against a command to show whether it would be allowed, prompted or blocked, which is the way to test a policy before trusting it. --log-denials on macOS prints what the sandbox blocked after a command exits.
codex exec runs one prompt non-interactively for scripts and CI, streaming to stdout; add --json, --experimental-json for newline-delimited events, --output-last-message, -o to write the final answer to a file, and --output-schema to validate it against a JSON Schema. --last resumes the most recent session and --ephemeral leaves no session files behind. codex review reviews changes — --uncommitted for the working tree, --base against a branch, --commit for one commit — and prints findings without editing. codex doctor diagnoses install, auth and Git problems, and codex mcp registers tool servers.
codex opens the interactive TUI. codex exec runs a single prompt to completion without a UI, for scripts and CI.
Lower the approval mode with -a, or use a permission profile with -P. --yolo disables approvals and the sandbox entirely and should only run inside a hardened container.
codex exec --last resumes the most recent session in the current directory; pass a SESSION_ID to resume a specific one.
Use codex exec with --json for event streams, or --output-schema with a JSON Schema file to validate the final message.
Open your assistant with this page preloaded as the source — great for follow-up questions like "which of these work in other apps?"