Skip to main content
Watch: I Built an AI App Without Leaving Databricks

Codex CLI reference - CLI flags

Codex CLI command-line flags

Codex CLI documents 136 CLI flags, including --add-dir, --dangerously-bypass-hook-trust and --disable. You pass these to codex on the command line. Each row gives the docs' description, accepted values and an example where one is documented.

Last verified 1 official pageFull Codex CLI reference

Codex CLI CLI flags
FlagDescriptionExample
--add-dir

Grant additional directories write access alongside the main workspace. Repeat for multiple paths.

path

Docs: --add-dir		-no example
--approve-for-me, --not-so-yolo

Use automatic approval review with on-request approvals and the workspace-write sandbox. Conflicts with --sandbox and --yolo; the interactive CLI also rejects --ask-for-approval.

boolean

Docs: --approve-for-me, --not-so-yolo		-no example
--ask-for-approval, -a

Control when Codex pauses for human approval before running a command.

on-request | never

Docs: --ask-for-approval, -a
codex --ask-for-approval never "Summarize the current instructions."
--cd, -C

Set the working directory for the agent before it starts processing your request.

path

Docs: --cd, -C
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
--config, -c

Override configuration values. Values parse as TOML if possible; otherwise the literal string is used.

key=value

Docs: --config, -c
codex --config model='"gpt-6.1-sol"'
--dangerously-bypass-approvals-and-sandbox, --yolo

Run every command without approvals or sandboxing. Only use inside an externally hardened environment.

boolean

Docs: --dangerously-bypass-approvals-and-sandbox, --yolo		-no example
--dangerously-bypass-hook-trust

Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources.

boolean

Docs: --dangerously-bypass-hook-trust		-no example
--disable

Force-disable a feature flag (translates to -c features.<name>=false). Repeatable.

feature

Docs: --disable		-no example
--enable

Force-enable a feature flag (translates to -c features.<name>=true). Repeatable.

feature

Docs: --enable
codex --enable feature_a --enable feature_b
--image, -i

Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.

path[,path...]

Docs: --image, -i		-no example
--local-provider

Choose the local provider used with --oss, overriding oss_provider for this run.

lmstudio | ollama

Docs: --local-provider		-no example
--model, -m

Override the model set in configuration (for example gpt-6.1-sol).

string

Docs: --model, -m
codex --model gpt-6.1-sol
--no-alt-screen

Disable alternate screen mode for the TUI (overrides tui.alternate_screen for this run).

boolean

Docs: --no-alt-screen		-no example
--no-daemon

Run the interactive CLI without the shared background server. Can't be combined with --remote or codex agents.

boolean

Docs: --no-daemon		-no example
--oss

Use a local open source model provider. Codex uses --local-provider, your configured oss_provider, or prompts you to choose between LM Studio and Ollama.

boolean

Docs: --oss		-no example
--profile, -p

Layer $CODEX_HOME/profile-name.config.toml on top of the base user config.

string

Docs: --profile, -p
codex --profile deep-review
--remote

Connect to a remote app-server endpoint over WebSocket or a Unix socket. Supported for codex, codex agents, codex queue, codex resume, codex fork, codex archive, codex delete, and codex unarchive; other subcommands reject remote mode.

ws://host:port | wss://host:port | unix:// | unix://PATH

Docs: --remote
--remote ws://host:port
--remote-auth-token-env

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 local-only ws:// URLs.

ENV_VAR

Docs: --remote-auth-token-env		-no example
--sandbox, -s

Select the sandbox policy for model-generated shell commands.

read-only | workspace-write | danger-full-access

Docs: --sandbox, -s
--sandbox workspace-write --ask-for-approval on-request
--search

Enable live web search (sets web_search = "live" instead of the default "cached").

boolean

Docs: --search		-no example
--strict-config

Error when config.toml contains fields this Codex version does not recognize. Supported by runtime commands such as codex, exec, review, resume, fork, app-server, and exec-server.

boolean

Docs: --strict-config		-no example
--worktree

Start in a new managed Git worktree. Supports new interactive sessions, codex fork <SESSION_ID>, codex exec, and codex exec fork; requires local execution.

boolean

Docs: --worktree		-no example
PROMPT

Positional arg of codex: Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.

string

Docs: PROMPT		-no example
--analytics-default-enabled

codex app-server: Defaults analytics to enabled for first-party app-server clients unless the user opts out in config.

boolean

Docs: --analytics-default-enabled		-no example
--code-mode-host

codex app-server: Connect to a remote Code Mode host instead of starting a local host. This outbound connection is shared across threads and is separate from --listen; use wss:// for remote hosts.

ws://HOST/PATH | wss://HOST/PATH

Docs: --code-mode-host
--code-mode-host wss://code-mode.example.com/host
--listen

codex app-server: Transport listener URL. Use stdio:// for JSONL, ws://IP:PORT for a TCP WebSocket endpoint, unix:// for the default Unix socket, unix://PATH for a custom Unix socket, or off to disable the local transport.

stdio:// | ws://IP:PORT | unix:// | unix://PATH | off

Docs: --listen
codex app-server --listen ws://IP:PORT
--stdio

codex app-server: Use stdio transport. Equivalent to --listen stdio:// and mutually exclusive with --listen.

boolean

Docs: --stdio		-no example
--ws-audience

codex app-server: Expected aud claim for signed bearer tokens. Requires --ws-auth signed-bearer-token.

string

Docs: --ws-audience		-no example
--ws-auth

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

capability-token | signed-bearer-token

Docs: --ws-auth		-no example
--ws-issuer

codex app-server: Expected iss claim for signed bearer tokens. Requires --ws-auth signed-bearer-token.

string

Docs: --ws-issuer		-no example
--ws-max-clock-skew-seconds

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

number

Docs: --ws-max-clock-skew-seconds		-no example
--ws-shared-secret-file

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

absolute path

Docs: --ws-shared-secret-file		-no example
--ws-token-file

codex app-server: File containing the shared capability token. Use with --ws-auth capability-token unless you provide --ws-token-sha256 instead.

absolute path

Docs: --ws-token-file		-no example
--ws-token-sha256

codex app-server: Expected SHA-256 digest for capability-token authentication. Use instead of --ws-token-file when the client token comes from another source.

hexadecimal SHA-256 digest

Docs: --ws-token-sha256		-no example
--download-url

codex app: Advanced override for the ChatGPT desktop app installer URL used during install.

url

Docs: --download-url		-no example
PATH

Positional arg of codex app: Workspace path for the ChatGPT desktop app. On macOS, Codex opens this path; on Windows, Codex prints the path.

path

Docs: PATH		-no example
USER_MESSAGE

Positional arg of codex debug app-server send-message-v2: Message text sent to app-server through the built-in V2 test-client flow.

string

Docs: USER_MESSAGE		-no example
--bundled

codex debug models: Skip refresh and print only the model catalog bundled with the current Codex binary.

boolean

Docs: --bundled		-no example
--image, -i

codex debug prompt-input: Attach one or more images to the user prompt. Separate multiple paths with commas or repeat the flag.

path[,path...]

Docs: --image, -i		-no example
PROMPT

Positional arg of codex debug prompt-input: Optional user prompt appended after the session context.

string

Docs: PROMPT		-no example
TASK_ID

Positional arg of codex apply: Identifier of the Codex cloud chat whose diff should be applied.

string

Docs: TASK_ID		-no example
--base

codex review: Review changes against the specified base branch.

branch

Docs: --base		-no example
--commit

codex review: Review the changes introduced by the specified commit.

SHA

Docs: --commit		-no example
--strict-config

codex review: Error when config.toml contains fields this Codex version does not recognize.

boolean

Docs: --strict-config		-no example
--title

codex review: Set the commit title shown in the review summary. Requires --commit.

string

Docs: --title		-no example
--uncommitted

codex review: Review staged, unstaged, and untracked changes.

boolean

Docs: --uncommitted		-no example
PROMPT

Positional arg of codex review: Custom review instructions. Use - to read the instructions from stdin.

string | - (read stdin)

Docs: PROMPT		-no example
--remote

codex archive / codex unarchive: Connect to a remote app-server endpoint before changing archive state.

ws://host:port | wss://host:port | unix:// | unix://PATH

Docs: --remote		-no example
--remote-auth-token-env

codex archive / codex unarchive: Read a bearer token from this environment variable when --remote requires authentication.

ENV_VAR

Docs: --remote-auth-token-env		-no example
SESSION

Positional arg of codex archive / codex unarchive: Saved session to archive or restore. Session IDs take precedence over session names.

session ID | session name

Docs: SESSION
codex archive <SESSION> codex unarchive <SESSION>
--force

codex delete: Delete without prompting. The session argument must be a UUID; names still require interactive confirmation.

boolean

Docs: --force
codex delete <SESSION_UUID> --force
--remote

codex delete: Connect to a remote app-server endpoint before deleting the session.

ws://host:port | wss://host:port | unix:// | unix://PATH

Docs: --remote		-no example
--remote-auth-token-env

codex delete: Read a bearer token from this environment variable when --remote requires authentication.

ENV_VAR

Docs: --remote-auth-token-env		-no example
SESSION

Positional arg of codex delete: Saved session to delete. Session IDs take precedence over session names.

session ID | session name

Docs: SESSION
codex delete <SESSION>
--attempts

codex cloud: Number of assistant attempts (best-of-N) Codex cloud should run.

1-4

Docs: --attempts		-no example
--env

codex cloud: Target Codex cloud environment identifier (required). Use codex cloud to list options.

ENV_ID

Docs: --env		-no example
QUERY

Positional arg of codex cloud: Task prompt. If omitted, Codex prompts interactively for details.

string

Docs: QUERY		-no example
--cursor

codex cloud list: Pagination cursor returned by a previous request.

string

Docs: --cursor		-no example
--env

codex cloud list: Filter tasks by environment identifier.

ENV_ID

Docs: --env		-no example
--json

codex cloud list: Emit machine-readable JSON instead of plain text.

boolean

Docs: --json		-no example
--limit

codex cloud list: Maximum number of tasks to return.

1-20

Docs: --limit		-no example
SHELL

Positional arg of codex completion: Shell to generate completions for. Output prints to stdout.

bash | zsh | fish | power-shell | elvish

Docs: SHELL
codex completion zsh > "${fpath[1]}/_codex"
--all

codex doctor: Expand long lists in the detailed human-readable report.

boolean

Docs: --all		-no example
--ascii

codex doctor: Use ASCII status labels and separators in human-readable output.

boolean

Docs: --ascii		-no example
--json

codex doctor: Emit a redacted machine-readable support report.

boolean

Docs: --json		-no example
--no-color

codex doctor: Disable ANSI color in human-readable output.

boolean

Docs: --no-color		-no example
--summary

codex doctor: Show grouped check rows and the final count summary only.

boolean

Docs: --summary		-no example
--approve-for-me, --not-so-yolo

codex exec: Use automatic approval review with on-request approvals and the workspace-write sandbox. Conflicts with --sandbox and --yolo; the interactive CLI also rejects --ask-for-approval.

boolean

Docs: --approve-for-me, --not-so-yolo		-no example
--cd, -C

codex exec: Set the workspace root before executing the task.

path

Docs: --cd, -C		-no example
--color

codex exec: Control ANSI color in stdout.

always | never | auto

Docs: --color		-no example
--dangerously-bypass-approvals-and-sandbox, --yolo

codex exec: Bypass approval prompts and sandboxing. Dangerous - only use inside an isolated runner.

boolean

Docs: --dangerously-bypass-approvals-and-sandbox, --yolo		-no example
--dangerously-bypass-hook-trust

codex exec: Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources.

boolean

Docs: --dangerously-bypass-hook-trust		-no example
--ephemeral

codex exec: Run without persisting session rollout files to disk.

boolean

Docs: --ephemeral		-no example
--ignore-rules

codex exec: Do not load user or project execpolicy .rules files for this run.

boolean

Docs: --ignore-rules		-no example
--ignore-user-config

codex exec: Do not load $CODEX_HOME/config.toml. Authentication still uses CODEX_HOME.

boolean

Docs: --ignore-user-config		-no example
--image, -i

codex exec: Attach images to the first message. Repeatable; supports comma-separated lists.

path[,path...]

Docs: --image, -i		-no example
--json, --experimental-json

codex exec: Print newline-delimited JSON events instead of formatted text.

boolean

Docs: --json, --experimental-json		-no example
--local-provider

codex exec: Choose the local provider used with --oss, overriding oss_provider for this run.

lmstudio | ollama

Docs: --local-provider		-no example
--model, -m

codex exec: Override the configured model for this run.

string

Docs: --model, -m		-no example
--oss

codex exec: Use a local open source provider. Codex uses --local-provider or your configured oss_provider, and exits with an error if neither is set.

boolean

Docs: --oss		-no example
--output-last-message, -o

codex exec: Write the assistant’s final message to a file. Useful for downstream scripting.

path

Docs: --output-last-message, -o		-no example
--output-schema

codex exec: JSON Schema file describing the expected final response shape. Codex validates tool output against it.

path

Docs: --output-schema		-no example
--profile, -p

codex exec: Layer $CODEX_HOME/profile-name.config.toml on top of the base user config.

string

Docs: --profile, -p
codex exec --profile deep-review "review this change"
--sandbox, -s

codex exec: Sandbox policy for model-generated commands. Defaults to configuration.

read-only | workspace-write | danger-full-access

Docs: --sandbox, -s		-no example
--skip-git-repo-check

codex exec: Allow running outside a Git repository (useful for one-off directories).

boolean

Docs: --skip-git-repo-check		-no example
--worktree

codex exec: Run a new or forked session in a managed Git worktree. Requires local execution; can't be combined with resume, review, --ephemeral, or --ignore-user-config.

boolean

Docs: --worktree		-no example
-c, --config

codex exec: Inline configuration override for the non-interactive run (repeatable).

key=value

Docs: -c, --config		-no example
PROMPT

Positional arg of codex exec: Initial instruction for the task. Use - to pipe the prompt from stdin.

string | - (read stdin)

Docs: PROMPT		-no example
--all

codex exec resume: Include sessions outside the current working directory when selecting the most recent session.

boolean

Docs: --all		-no example
--image, -i

codex exec resume: Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.

path[,path...]

Docs: --image, -i		-no example
--last

codex exec resume: Resume the most recent chat from the current working directory.

boolean

Docs: --last		-no example
PROMPT

Positional arg of codex exec resume: Optional follow-up instruction sent immediately after resuming.

string | - (read stdin)

Docs: PROMPT		-no example
SESSION_ID

Positional arg of codex exec resume: Resume the specified session. Omit and use --last to continue the most recent session.

uuid | session name

Docs: SESSION_ID		-no example
--pretty

codex execpolicy: Pretty-print the JSON result.

boolean

Docs: --pretty
codex execpolicy check --pretty \ --rules ~/.codex/rules/default.rules \ -- gh pr view 7888 --json title,body,comments
--rules, -r

codex execpolicy: Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.

path (repeatable)

Docs: --rules, -r
codex execpolicy check --pretty \ --rules ~/.codex/rules/default.rules \ -- gh pr view 7888 --json title,body,comments
COMMAND...

Positional arg of codex execpolicy: Command to be checked against the specified policies.

var-args

Docs: COMMAND...		-no example
--device-auth

codex login: Use OAuth device code flow instead of launching a browser window.

boolean

Docs: --device-auth		-no example
--with-access-token

codex login: Read an access token from stdin (for example printenv CODEX_ACCESS_TOKEN | codex login --with-access-token).

boolean

Docs: --with-access-token
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token
--with-api-key

codex login: Read an API key from stdin (for example printenv OPENAI_API_KEY | codex login --with-api-key).

boolean

Docs: --with-api-key
printenv OPENAI_API_KEY | codex login --with-api-key
--bearer-token-env-var

codex mcp add: Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.

ENV_VAR

Docs: --bearer-token-env-var		-no example
--env KEY=VALUE

codex mcp add: Environment variable assignments applied when launching a stdio server.

repeatable

Docs: --env KEY=VALUE		-no example
--oauth-client-id

codex mcp add: OAuth client identifier for a streamable HTTP MCP server. Requires --url.

CLIENT_ID

Docs: --oauth-client-id		-no example
--oauth-resource

codex mcp add: OAuth resource parameter to include during login for a streamable HTTP MCP server. Requires --url.

RESOURCE

Docs: --oauth-resource		-no example
--url

codex mcp add: Register a streamable HTTP server instead of stdio. Mutually exclusive with COMMAND....

https://…

Docs: --url		-no example
COMMAND...

Positional arg of codex mcp add: Executable plus arguments to launch the MCP server. Provide after --.

stdio transport

Docs: COMMAND...		-no example
--all

codex resume: Include sessions outside the current working directory when selecting the most recent session.

boolean

Docs: --all		-no example
--include-non-interactive

codex resume: Include non-interactive sessions in the picker and --last selection.

boolean

Docs: --include-non-interactive		-no example
--last

codex resume: Skip the picker and resume the most recent chat from the current working directory.

boolean

Docs: --last		-no example
SESSION_ID

Positional arg of codex resume: Resume the specified session. Omit and use --last to continue the most recent session.

uuid | session name

Docs: SESSION_ID		-no example
--all

codex fork: Show sessions beyond the current working directory in the picker.

boolean

Docs: --all		-no example
--last

codex fork: Skip the picker and fork the most recent chat automatically.

boolean

Docs: --last		-no example
SESSION_ID

Positional arg of codex fork: Fork the specified session. Omit and use --last to fork the most recent session.

uuid

Docs: SESSION_ID		-no example
--allow-unix-socket

codex sandbox (macOS seatbelt): Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths.

path

Docs: --allow-unix-socket		-no example
--cd, -C

codex sandbox (macOS seatbelt): Working directory used for profile resolution and command execution. Requires --permission-profile.

DIR

Docs: --cd, -C		-no example
--config, -c

codex sandbox (macOS seatbelt): Pass configuration overrides into the sandboxed run (repeatable).

key=value

Docs: --config, -c		-no example
--include-managed-config

codex sandbox (macOS seatbelt): Include managed requirements while resolving an explicit permissions profile. Requires --permission-profile.

boolean

Docs: --include-managed-config		-no example
--log-denials

codex sandbox (macOS seatbelt): Capture macOS sandbox denials with log stream while the command runs and print them after exit.

boolean

Docs: --log-denials		-no example
--permission-profile, -P

codex sandbox (macOS seatbelt): Apply a named permissions profile from the active configuration stack.

NAME

Docs: --permission-profile, -P		-no example
--profile, -p

codex sandbox (macOS seatbelt): Layer $CODEX_HOME/NAME.config.toml on top of the base user config.

NAME

Docs: --profile, -p		-no example
COMMAND...

Positional arg of codex sandbox (macOS seatbelt): Shell command to execute under macOS Seatbelt. Everything after -- is forwarded.

var-args

Docs: COMMAND...		-no example
--cd, -C

codex sandbox (Linux sandbox): Working directory used for profile resolution and command execution. Requires --permission-profile.

DIR

Docs: --cd, -C		-no example
--config, -c

codex sandbox (Linux sandbox): Configuration overrides applied before launching the sandbox (repeatable).

key=value

Docs: --config, -c		-no example
--include-managed-config

codex sandbox (Linux sandbox): Include managed requirements while resolving an explicit permissions profile. Requires --permission-profile.

boolean

Docs: --include-managed-config		-no example
--permission-profile, -P

codex sandbox (Linux sandbox): Apply a named permissions profile from the active configuration stack.

NAME

Docs: --permission-profile, -P		-no example
--profile, -p

codex sandbox (Linux sandbox): Layer $CODEX_HOME/NAME.config.toml on top of the base user config.

NAME

Docs: --profile, -p		-no example
COMMAND...

Positional arg of codex sandbox (Linux sandbox): Command to execute with bubblewrap filesystem isolation and seccomp filtering. Provide the executable after --.

var-args

Docs: COMMAND...		-no example
--cd, -C

codex sandbox (Windows): Working directory used for profile resolution and command execution. Requires --permission-profile.

DIR

Docs: --cd, -C		-no example
--config, -c

codex sandbox (Windows): Configuration overrides applied before launching the sandbox (repeatable).

key=value

Docs: --config, -c		-no example
--include-managed-config

codex sandbox (Windows): Include managed requirements while resolving an explicit permissions profile. Requires --permission-profile.

boolean

Docs: --include-managed-config		-no example
--permission-profile, -P

codex sandbox (Windows): Apply a named permissions profile from the active configuration stack.

NAME

Docs: --permission-profile, -P		-no example
--profile, -p

codex sandbox (Windows): Layer $CODEX_HOME/NAME.config.toml on top of the base user config.

NAME

Docs: --profile, -p		-no example
COMMAND...

Positional arg of codex sandbox (Windows): Command to execute under the native Windows sandbox. Provide the executable after --.

var-args

Docs: COMMAND...		-no example
--thread

codex queue: Session to queue the message for; accepts a UUID or exact session name. Use a UUID when sessions share the same name.

UUID | exact session name

Docs: --thread
codex queue --thread <SESSION_ID> --message "Run the remaining checks"
--message

codex queue: Text message to queue for the existing session; image attachments are not supported.

string

Docs: --message
codex queue --thread <SESSION_ID> --message "Run the remaining checks"
--json

codex remote-control: Machine-readable output for any remote-control command.

boolean

Docs: --json		-no example
--no-daemon

codex remote-control: Run remote control in the foreground explicitly. Applies only to the bare remote-control command; do not combine it with start, stop, or pair.

boolean

Docs: --no-daemon
codex remote-control --no-daemon

The rest of the Codex CLI reference

FAQ

How many CLI flags does Codex CLI have?

The official Codex CLI docs list 136 CLI flags, including --add-dir, --dangerously-bypass-hook-trust and --disable. All of them are in the table above, in the docs' order.

What does --add-dir do in Codex CLI?

Grant additional directories write access alongside the main workspace. Repeat for multiple paths. Values: path.

Where are Codex CLI command-line flags documented?

On 1 official docs page at learn.chatgpt.com, last read on October 17, 2026. Every row in the table links the exact section it came from.

More on Codex CLI

Use other models in Codex CLI

Setup guides from the model-in-tool directory, each with the env vars and base URL from official docs.

Sources

Last verified . Names and examples are copied verbatim from the official page below, and every row above links the exact section it came from.

Newsletter

Know when your tools change

One email per week. New coding agent releases, the flags and commands they add, and what they mean for how you work.