Primary navigation
API Dashboard

Command line options

Options and flags for the Codex terminal client

How to read this reference

This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.

The CLI inherits most defaults from ~/.codex/config.toml. Any -c key=value overrides you pass at the command line take precedence for that invocation. See Config basics for more information.

Global flags

Key
--add-dir
Type / Values
path
Details
Grant additional directories write access alongside the main workspace. Repeat for multiple paths.
Key
--ask-for-approval, -a
Type / Values
untrusted | on-request | never
Details
Control when Codex pauses for human approval before running a command. on-failure is deprecated; prefer on-request for interactive runs or never for non-interactive runs.
Key
--cd, -C
Type / Values
path
Details
Set the working directory for the agent before it starts processing your request.
Key
--config, -c
Type / Values
key=value
Details
Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.
Key
--dangerously-bypass-approvals-and-sandbox, --yolo
Type / Values
boolean
Details
Run every command without approvals or sandboxing. Only use inside an externally hardened environment.
Key
--disable
Type / Values
feature
Details
Force-disable a feature flag (translates to -c features.<name>=false). Repeatable.
Key
--enable
Type / Values
feature
Details
Force-enable a feature flag (translates to -c features.<name>=true). Repeatable.
Key
--full-auto
Type / Values
boolean
Details
Shortcut for low-friction local work: sets --ask-for-approval on-request and --sandbox workspace-write.
Key
--image, -i
Type / Values
path[,path...]
Details
Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.
Key
--model, -m
Type / Values
string
Details
Override the model set in configuration (for example gpt-5-codex).
Key
--no-alt-screen
Type / Values
boolean
Details
Disable alternate screen mode for the TUI (overrides tui.alternate_screen for this run).
Key
--oss
Type / Values
boolean
Details
Use the local open source model provider (equivalent to -c model_provider="oss"). Validates that Ollama is running.
Key
--profile, -p
Type / Values
string
Details
Configuration profile name to load from ~/.codex/config.toml.
Key
--sandbox, -s
Type / Values
read-only | workspace-write | danger-full-access
Details
Select the sandbox policy for model-generated shell commands.
Key
--search
Type / Values
boolean
Details
Enable live web search (sets web_search = "live" instead of the default "cached").
Key
PROMPT
Type / Values
string
Details
Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.

These options apply to the base codex command and propagate to each subcommand unless a section below specifies otherwise. When you run a subcommand, place global flags after it (for example, codex exec --oss ...) so Codex applies them as intended.

Command overview

The Maturity column uses feature maturity labels such as Experimental, Beta, and Stable. See Feature Maturity for how to interpret these labels.

Key
codex
Maturity
Stable
Details
Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.
Key
codex app
Maturity
Stable
Details
Launch the Codex desktop app on macOS, optionally opening a specific workspace path.
Key
codex app-server
Maturity
Experimental
Details
Launch the Codex app server for local development or debugging.
Key
codex apply
Maturity
Stable
Details
Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: codex a.
Key
codex cloud
Maturity
Experimental
Details
Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: codex cloud-tasks.
Key
codex completion
Maturity
Stable
Details
Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.
Key
codex debug app-server send-message-v2
Maturity
Experimental
Details
Debug app-server by sending a single V2 message through the built-in test client.
Key
codex exec
Maturity
Stable
Details
Run Codex non-interactively. Alias: codex e. Stream results to stdout or JSONL and optionally resume previous sessions.
Key
codex execpolicy
Maturity
Experimental
Details
Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.
Key
codex features
Maturity
Stable
Details
List feature flags and persistently enable or disable them in config.toml.
Key
codex fork
Maturity
Stable
Details
Fork a previous interactive session into a new thread, preserving the original transcript.
Key
codex login
Maturity
Stable
Details
Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.
Key
codex logout
Maturity
Stable
Details
Remove stored authentication credentials.
Key
codex mcp
Maturity
Experimental
Details
Manage Model Context Protocol servers (list, add, remove, authenticate).
Key
codex mcp-server
Maturity
Experimental
Details
Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.
Key
codex resume
Maturity
Stable
Details
Continue a previous interactive session by ID or resume the most recent conversation.
Key
codex sandbox
Maturity
Experimental
Details
Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline).

Command details

codex (interactive)

Running codex with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use --search to switch to live browsing and --full-auto to let Codex run most commands without prompts.

codex app-server

Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.

Key
--listen
Type / Values
stdio:// | ws://IP:PORT
Details
Transport listener URL. ws:// is experimental and intended for development/testing.

codex app-server --listen stdio:// keeps the default JSONL-over-stdio behavior. --listen ws://IP:PORT enables WebSocket transport (experimental). If you generate schemas for client bindings, add --experimental to include gated fields and methods.

codex app

Launch Codex Desktop from the terminal on macOS and optionally open a specific workspace path.

Key
--download-url
Type / Values
url
Details
Advanced override for the Codex desktop DMG download URL used during install.
Key
PATH
Type / Values
path
Details
Workspace path to open in Codex Desktop (codex app is available on macOS only).

codex app installs/opens the desktop app on macOS, then opens the provided workspace path. This subcommand is macOS-only.

codex debug app-server send-message-v2

Send one message through app-server’s V2 thread/turn flow using the built-in app-server test client.

Key
USER_MESSAGE
Type / Values
string
Details
Message text sent to app-server through the built-in V2 test-client flow.

This debug flow initializes with experimentalApi: true, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.

codex apply

Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.

Key
TASK_ID
Type / Values
string
Details
Identifier of the Codex Cloud task whose diff should be applied.

Codex prints the patched files and exits non-zero if git apply fails (for example, due to conflicts).

codex cloud

Interact with Codex cloud tasks from the terminal. The default command opens an interactive picker; codex cloud exec submits a task directly, and codex cloud list returns recent tasks for scripting or quick inspection.

Key
--attempts
Type / Values
1-4
Details
Number of assistant attempts (best-of-N) Codex Cloud should run.
Key
--env
Type / Values
ENV_ID
Details
Target Codex Cloud environment identifier (required). Use codex cloud to list options.
Key
QUERY
Type / Values
string
Details
Task prompt. If omitted, Codex prompts interactively for details.

Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.

codex cloud list

List recent cloud tasks with optional filtering and pagination.

Key
--cursor
Type / Values
string
Details
Pagination cursor returned by a previous request.
Key
--env
Type / Values
ENV_ID
Details
Filter tasks by environment identifier.
Key
--json
Type / Values
boolean
Details
Emit machine-readable JSON instead of plain text.
Key
--limit
Type / Values
1-20
Details
Maximum number of tasks to return.

Plain-text output prints a task URL followed by status details. Use --json for automation. The JSON payload contains a tasks array plus an optional cursor value. Each task includes id, url, title, status, updated_at, environment_id, environment_label, summary, is_review, and attempt_total.

codex completion

Generate shell completion scripts and redirect the output to the appropriate location, for example codex completion zsh > "${fpath[1]}/_codex".

Key
SHELL
Type / Values
bash | zsh | fish | power-shell | elvish
Details
Shell to generate completions for. Output prints to stdout.

codex features

Manage feature flags stored in ~/.codex/config.toml. The enable and disable commands persist changes so they apply to future sessions. When you launch with --profile, Codex writes to that profile instead of the root configuration.

Key
Disable subcommand
Type / Values
codex features disable <feature>
Details
Persistently disable a feature flag in config.toml. Respects the active --profile when provided.
Key
Enable subcommand
Type / Values
codex features enable <feature>
Details
Persistently enable a feature flag in config.toml. Respects the active --profile when provided.
Key
List subcommand
Type / Values
codex features list
Details
Show known feature flags, their maturity stage, and their effective state.

codex exec

Use codex exec (or the short form codex e) for scripted or CI-style runs that should finish without human interaction.

Key
--cd, -C
Type / Values
path
Details
Set the workspace root before executing the task.
Key
--color
Type / Values
always | never | auto
Details
Control ANSI color in stdout.
Key
--dangerously-bypass-approvals-and-sandbox, --yolo
Type / Values
boolean
Details
Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.
Key
--ephemeral
Type / Values
boolean
Details
Run without persisting session rollout files to disk.
Key
--full-auto
Type / Values
boolean
Details
Apply the low-friction automation preset (workspace-write sandbox and on-request approvals).
Key
--image, -i
Type / Values
path[,path...]
Details
Attach images to the first message. Repeatable; supports comma-separated lists.
Key
--json, --experimental-json
Type / Values
boolean
Details
Print newline-delimited JSON events instead of formatted text.
Key
--model, -m
Type / Values
string
Details
Override the configured model for this run.
Key
--oss
Type / Values
boolean
Details
Use the local open source provider (requires a running Ollama instance).
Key
--output-last-message, -o
Type / Values
path
Details
Write the assistant’s final message to a file. Useful for downstream scripting.
Key
--output-schema
Type / Values
path
Details
JSON Schema file describing the expected final response shape. Codex validates tool output against it.
Key
--profile, -p
Type / Values
string
Details
Select a configuration profile defined in config.toml.
Key
--sandbox, -s
Type / Values
read-only | workspace-write | danger-full-access
Details
Sandbox policy for model-generated commands. Defaults to configuration.
Key
--skip-git-repo-check
Type / Values
boolean
Details
Allow running outside a Git repository (useful for one-off directories).
Key
-c, --config
Type / Values
key=value
Details
Inline configuration override for the non-interactive run (repeatable).
Key
PROMPT
Type / Values
string | - (read stdin)
Details
Initial instruction for the task. Use - to pipe the prompt from stdin.
Key
Resume subcommand
Type / Values
codex exec resume [SESSION_ID]
Details
Resume an exec session by ID or add --last to continue the most recent session from the current working directory. Add --all to consider sessions from any directory. Accepts an optional follow-up prompt.

Codex writes formatted output by default. Add --json to receive newline-delimited JSON events (one per state change). The optional resume subcommand lets you continue non-interactive tasks. Use --last to pick the most recent session from the current working directory, or add --all to search across all sessions:

Key
--all
Type / Values
boolean
Details
Include sessions outside the current working directory when selecting the most recent session.
Key
--image, -i
Type / Values
path[,path...]
Details
Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.
Key
--last
Type / Values
boolean
Details
Resume the most recent conversation from the current working directory.
Key
PROMPT
Type / Values
string | - (read stdin)
Details
Optional follow-up instruction sent immediately after resuming.
Key
SESSION_ID
Type / Values
uuid
Details
Resume the specified session. Omit and use --last to continue the most recent session.

codex execpolicy

Check execpolicy rule files before you save them. codex execpolicy check accepts one or more --rules flags (for example, files under ~/.codex/rules) and emits JSON showing the strictest decision and any matching rules. Add --pretty to format the output. The execpolicy command is currently in preview.

Key
--pretty
Type / Values
boolean
Details
Pretty-print the JSON result.
Key
--rules, -r
Type / Values
path (repeatable)
Details
Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.
Key
COMMAND...
Type / Values
var-args
Details
Command to be checked against the specified policies.

codex login

Authenticate the CLI with a ChatGPT account or API key. With no flags, Codex opens a browser for the ChatGPT OAuth flow.

Key
--device-auth
Type / Values
boolean
Details
Use OAuth device code flow instead of launching a browser window.
Key
--with-api-key
Type / Values
boolean
Details
Read an API key from stdin (for example printenv OPENAI_API_KEY | codex login --with-api-key).
Key
status subcommand
Type / Values
codex login status
Details
Print the active authentication mode and exit with 0 when logged in.

codex login status exits with 0 when credentials are present, which is helpful in automation scripts.

codex logout

Remove saved credentials for both API key and ChatGPT authentication. This command has no flags.

codex mcp

Manage Model Context Protocol server entries stored in ~/.codex/config.toml.

Key
add <name>
Type / Values
-- <command...> | --url <value>
Details
Register a server using a stdio launcher command or a streamable HTTP URL. Supports --env KEY=VALUE for stdio transports.
Key
get <name>
Type / Values
--json
Details
Show a specific server configuration. --json prints the raw config entry.
Key
list
Type / Values
--json
Details
List configured MCP servers. Add --json for machine-readable output.
Key
login <name>
Type / Values
--scopes scope1,scope2
Details
Start an OAuth login for a streamable HTTP server (servers that support OAuth only).
Key
logout <name>
Details
Remove stored OAuth credentials for a streamable HTTP server.
Key
remove <name>
Details
Delete a stored MCP server definition.

The add subcommand supports both stdio and streamable HTTP transports:

Key
--bearer-token-env-var
Type / Values
ENV_VAR
Details
Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.
Key
--env KEY=VALUE
Type / Values
repeatable
Details
Environment variable assignments applied when launching a stdio server.
Key
--url
Type / Values
https://…
Details
Register a streamable HTTP server instead of stdio. Mutually exclusive with COMMAND....
Key
COMMAND...
Type / Values
stdio transport
Details
Executable plus arguments to launch the MCP server. Provide after --.

OAuth actions (login, logout) only work with streamable HTTP servers (and only when the server supports OAuth).

codex mcp-server

Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.

codex resume

Continue an interactive session by ID or resume the most recent conversation. codex resume scopes --last to the current working directory unless you pass --all. It accepts the same global flags as codex, including model and sandbox overrides.

Key
--all
Type / Values
boolean
Details
Include sessions outside the current working directory when selecting the most recent session.
Key
--last
Type / Values
boolean
Details
Skip the picker and resume the most recent conversation from the current working directory.
Key
SESSION_ID
Type / Values
uuid
Details
Resume the specified session. Omit and use --last to continue the most recent session.

codex fork

Fork a previous interactive session into a new thread. By default, codex fork opens the session picker; add --last to fork your most recent session instead.

Key
--all
Type / Values
boolean
Details
Show sessions beyond the current working directory in the picker.
Key
--last
Type / Values
boolean
Details
Skip the picker and fork the most recent conversation automatically.
Key
SESSION_ID
Type / Values
uuid
Details
Fork the specified session. Omit and use --last to fork the most recent session.

codex sandbox

Use the sandbox helper to run a command under the same policies Codex uses internally.

macOS seatbelt

Key
--config, -c
Type / Values
key=value
Details
Pass configuration overrides into the sandboxed run (repeatable).
Key
--full-auto
Type / Values
boolean
Details
Grant write access to the current workspace and /tmp without approvals.
Key
COMMAND...
Type / Values
var-args
Details
Shell command to execute under macOS Seatbelt. Everything after -- is forwarded.

Linux Landlock

Key
--config, -c
Type / Values
key=value
Details
Configuration overrides applied before launching the sandbox (repeatable).
Key
--full-auto
Type / Values
boolean
Details
Grant write access to the current workspace and /tmp inside the Landlock sandbox.
Key
COMMAND...
Type / Values
var-args
Details
Command to execute under Landlock + seccomp. Provide the executable after --.

Flag combinations and safety tips

  • Set --full-auto for unattended local work, but avoid combining it with --dangerously-bypass-approvals-and-sandbox unless you are inside a dedicated sandbox VM.
  • When you need to grant Codex write access to more directories, prefer --add-dir rather than forcing --sandbox danger-full-access.
  • Pair --json with --output-last-message in CI to capture machine-readable progress and a final natural-language summary.

Related resources