Primary navigation

Codex CLI reference

Complete command and flag catalog 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. Check out the Codex configuration page for more information.

Global flags

Key
PROMPT
Type / Values
string
Details

Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.

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
--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
--ask-for-approval, -a
Type / Values
untrusted | on-failure | on-request | never
Details

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

Key
--full-auto
Type / Values
boolean
Details

Shortcut for unattended local work: sets `--ask-for-approval on-failure` and `--sandbox workspace-write`.

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
--cd, -C
Type / Values
path
Details

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

Key
--search
Type / Values
boolean
Details

Enable web search. When true, the agent can call the `web_search` tool without asking every time.

Key
--add-dir
Type / Values
path
Details

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

Key
--enable
Type / Values
feature
Details

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

Key
--disable
Type / Values
feature
Details

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

Key
--config, -c
Type / Values
key=value
Details

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

These options apply to the base codex command and propagate to subcommands unless a section below specifies otherwise.

Command overview

Key
codex
Type / Values
stable
Details

Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.

Key
codex exec
Type / Values
stable
Details

Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.

Key
codex login
Type / Values
stable
Details

Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.

Key
codex logout
Type / Values
stable
Details

Remove stored authentication credentials.

Key
codex resume
Type / Values
stable
Details

Continue a previous interactive session by ID or resume the most recent conversation.

Key
codex apply
Type / Values
stable
Details

Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.

Key
codex sandbox
Type / Values
platform-specific
Details

Run arbitrary commands inside Codex-provided macOS seatbelt or Linux landlock sandboxes.

Key
codex completion
Type / Values
stable
Details

Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.

Key
codex mcp
Type / Values
experimental
Details

Manage Model Context Protocol servers (list, add, remove, authenticate).

Key
codex mcp-server
Type / Values
experimental
Details

Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.

Key
codex app-server
Type / Values
experimental
Details

Launch the Codex app server for local development or debugging.

Key
codex cloud
Type / Values
experimental
Details

Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.

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. Use --search to enable web browsing and --full-auto to let Codex run most commands without prompts.

codex exec

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

Key
PROMPT
Type / Values
string | - (read stdin)
Details

Initial instruction for the task. Use `-` to pipe the prompt from stdin.

Key
--image, -i
Type / Values
path[,path...]
Details

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

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
--sandbox, -s
Type / Values
read-only | workspace-write | danger-full-access
Details

Sandbox policy for model-generated commands. Defaults to configuration.

Key
--profile, -p
Type / Values
string
Details

Select a configuration profile defined in config.toml.

Key
--full-auto
Type / Values
boolean
Details

Apply the low-friction automation preset (`workspace-write` sandbox and approvals on failure).

Key
--dangerously-bypass-approvals-and-sandbox, --yolo
Type / Values
boolean
Details

Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.

Key
--cd, -C
Type / Values
path
Details

Set the workspace root before executing the task.

Key
--skip-git-repo-check
Type / Values
boolean
Details

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

Key
--output-schema
Type / Values
path
Details

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

Key
--color
Type / Values
always | never | auto
Details

Control ANSI color in stdout.

Key
--json, --experimental-json
Type / Values
boolean
Details

Print newline-delimited JSON events instead of formatted text.

Key
--output-last-message, -o
Type / Values
path
Details

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

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. Accepts an optional follow-up prompt.

Key
-c, --config
Type / Values
key=value
Details

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

Codex writes formatted output by default. Add --json to receive newline-delimited JSON events (one per state change). The optional resume subcommand makes it easy to continue non-interactive tasks:

Key
SESSION_ID
Type / Values
uuid
Details

Resume the specified session. Omit and use `--last` to continue the most recent session.

Key
--last
Type / Values
boolean
Details

Skip the picker and resume the most recent conversation automatically.

Key
PROMPT
Type / Values
string | - (read stdin)
Details

Optional follow-up instruction sent immediately after resuming.

codex login

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

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
--device-auth
Type / Values
boolean
Details

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

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

Removes saved credentials for both API key and ChatGPT authentication. No additional flags are required.

codex resume

Continue an interactive session by ID or resume the most recent conversation. codex resume accepts the same global flags as codex, including model and sandbox overrides.

Key
SESSION_ID
Type / Values
uuid
Details

Resume the specified session. Omit and use `--last` to continue the most recent session.

Key
--last
Type / Values
boolean
Details

Skip the picker and resume the most recent conversation automatically.

Key
PROMPT
Type / Values
string | - (read stdin)
Details

Optional follow-up instruction sent immediately after resuming.

codex apply

Apply the most recent diff from a Codex Cloud task to your local repository. You must be authenticated 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 sandbox

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

macOS seatbelt

Key
--full-auto
Type / Values
boolean
Details

Grant write access to the current workspace and `/tmp` without approvals.

Key
--config, -c
Type / Values
key=value
Details

Pass configuration overrides into the sandboxed run (repeatable).

Key
COMMAND...
Type / Values
var-args
Details

Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.

Linux landlock

Key
--full-auto
Type / Values
boolean
Details

Grant write access to the current workspace and `/tmp` inside the Landlock sandbox.

Key
--config, -c
Type / Values
key=value
Details

Configuration overrides applied before launching the sandbox (repeatable).

Key
COMMAND...
Type / Values
var-args
Details

Command to execute under Landlock + seccomp. Provide the executable after `--`.

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 mcp

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

Key
list
Type / Values
--json
Details

List configured MCP servers. Add `--json` for machine-readable output.

Key
get <name>
Type / Values
--json
Details

Show a specific server configuration. `--json` prints the raw config entry.

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
remove <name>
Details

Delete a stored MCP server definition.

Key
login <name>
Type / Values
--scopes scope1,scope2
Details

Start an OAuth login for a streamable HTTP server. Requires `experimental_use_rmcp_client = true`.

Key
logout <name>
Details

Remove stored OAuth credentials for a streamable HTTP server.

The add subcommand supports both stdio and streamable HTTP transports:

Key
COMMAND...
Type / Values
stdio transport
Details

Executable plus arguments to launch the MCP server. Provide after `--`.

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

OAuth actions (login, logout) require experimental_use_rmcp_client = true and only work with streamable HTTP servers.

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 app-server

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

codex cloud

Interact with Codex Cloud tasks from the terminal. The default command opens an interactive picker; codex cloud exec submits a task directly.

Key
QUERY
Type / Values
string
Details

Task prompt. If omitted, Codex prompts interactively for details.

Key
--env
Type / Values
ENV_ID
Details

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

Key
--attempts
Type / Values
1-4
Details

Number of assistant attempts (best-of-N) Codex Cloud should run.

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

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 additional 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.
  • codex mcp login requires the experimental_use_rmcp_client feature flag. Use --enable experimental_use_rmcp_client or update your config before running the command.

Related resources