Command line options

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

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

--remote

Type / Values

ws://host:port | wss://host:port

Details

Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for codex, codex resume, and codex fork; other subcommands reject remote mode.

Key

--remote-auth-token-env

Type / Values

ENV_VAR

Details

Read a bearer token from this environment variable and send it when connecting with --remote. Requires --remote; tokens are only sent over wss:// URLs or ws:// URLs whose host is localhost, 127.0.0.1, or ::1.

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.

Expand to view all

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 or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.

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 plugin marketplace

Maturity

Experimental

Details

Add, upgrade, or remove plugin marketplaces from Git or local sources.

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

Expand to view all

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.

Use --remote ws://host:port or --remote wss://host:port to connect the TUI to an app server started with codex app-server --listen ws://IP:PORT. Add --remote-auth-token-env <ENV_VAR> when the server requires a bearer token for WebSocket authentication. See Codex CLI features for setup examples and authentication guidance.

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. Use ws://IP:PORT to expose a WebSocket endpoint for remote clients.

Key

--ws-audience

Type / Values

string

Details

Expected aud claim for signed bearer tokens. Requires --ws-auth signed-bearer-token.

Key

--ws-auth

Type / Values

capability-token | signed-bearer-token

Details

Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.

Key

--ws-issuer

Type / Values

string

Details

Expected iss claim for signed bearer tokens. Requires --ws-auth signed-bearer-token.

Key

--ws-max-clock-skew-seconds

Type / Values

number

Details

Clock skew allowance when validating signed bearer token exp and nbf claims. Requires --ws-auth signed-bearer-token.

Key

--ws-shared-secret-file

Type / Values

absolute path

Details

File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with --ws-auth signed-bearer-token.

Key

--ws-token-file

Type / Values

absolute path

Details

File containing the shared capability token. Required with --ws-auth capability-token.

codex app-server --listen stdio:// keeps the default JSONL-over-stdio behavior. --listen ws://IP:PORT enables WebSocket transport for app-server clients. The server accepts ws:// listen URLs; use TLS termination or a secure proxy when clients connect with wss://. 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 or Windows. On macOS, Codex can open a specific workspace path; on Windows, Codex prints the path to open.

Key

--download-url

Type / Values

url

Details

Advanced override for the Codex desktop installer URL used during install.

Key

PATH

Type / Values

path

Details

Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.

codex app opens an installed Codex Desktop app, or starts the installer when the app is missing. On macOS, Codex opens the provided workspace path; on Windows, it prints the path to open after installation.

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.

Expand to view all

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 plugin marketplace

Manage plugin marketplace sources that Codex can browse and install from.

Key

add <source>

Type / Values

[--ref REF] [--sparse PATH]

Details

Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. --sparse is supported only for Git sources and can be repeated.

Key

remove <marketplace-name>

Details

Remove a configured plugin marketplace.

Key

upgrade [marketplace-name]

Details

Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.

codex plugin marketplace add accepts GitHub shorthand such as owner/repo or owner/repo@ref, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace root directories. Use --ref to pin a Git ref, and repeat --sparse PATH to use a sparse checkout for Git-backed marketplace repositories.

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

• Codex CLI overview: installation, upgrades, and quick tips.
• Config basics: persist defaults like the model and provider.
• Advanced Config: profiles, providers, sandbox tuning, and integrations.
• AGENTS.md: conceptual overview of Codex agent capabilities and best practices.