Command line options
Source URL: https://developers.openai.com/codex/cli/reference
Command line options
Section titled “Command line options”export const globalFlagOptions = [
{
key: “PROMPT”,
type: “string”,
description:
“Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.”,
},
{
key: “—image, -i”,
type: “path[,path…]”,
description:
“Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.”,
},
{
key: “—model, -m”,
type: “string”,
description:
“Override the model set in configuration (for example gpt-5-codex).”,
},
{
key: “—oss”,
type: “boolean”,
defaultValue: “false”,
description:
‘Use the local open source model provider (equivalent to -c model_provider="oss"). Validates that Ollama is running.’,
},
{
key: “—profile, -p”,
type: “string”,
description:
“Configuration profile name to load from ~/.codex/config.toml.”,
},
{
key: “—sandbox, -s”,
type: “read-only | workspace-write | danger-full-access”,
description:
“Select the sandbox policy for model-generated shell commands.”,
},
{
key: “—ask-for-approval, -a”,
type: “untrusted | on-request | never”,
description:
“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: “—full-auto”,
type: “boolean”,
defaultValue: “false”,
description:
“Shortcut for low-friction local work: sets --ask-for-approval on-request and --sandbox workspace-write.”,
},
{
key: “—dangerously-bypass-approvals-and-sandbox, —yolo”,
type: “boolean”,
defaultValue: “false”,
description:
“Run every command without approvals or sandboxing. Only use inside an externally hardened environment.”,
},
{
key: “—cd, -C”,
type: “path”,
description:
“Set the working directory for the agent before it starts processing your request.”,
},
{
key: “—search”,
type: “boolean”,
defaultValue: “false”,
description:
‘Enable live web search (sets web_search = "live" instead of the default "cached").’,
},
{
key: “—add-dir”,
type: “path”,
description:
“Grant additional directories write access alongside the main workspace. Repeat for multiple paths.”,
},
{
key: “—no-alt-screen”,
type: “boolean”,
defaultValue: “false”,
description:
“Disable alternate screen mode for the TUI (overrides tui.alternate_screen for this run).”,
},
{
key: “—enable”,
type: “feature”,
description:
“Force-enable a feature flag (translates to -c features.<name>=true). Repeatable.”,
},
{
key: “—disable”,
type: “feature”,
description:
“Force-disable a feature flag (translates to -c features.<name>=false). Repeatable.”,
},
{
key: “—config, -c”,
type: “key=value”,
description:
“Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.”,
},
];
export const commandOverview = [
{
key: “codex”,
href: “/codex/cli/reference#codex-interactive”,
type: “stable”,
description:
“Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.”,
},
{
key: “codex app-server”,
href: “/codex/cli/reference#codex-app-server”,
type: “experimental”,
description:
“Launch the Codex app server for local development or debugging.”,
},
{
key: “codex app”,
href: “/codex/cli/reference#codex-app”,
type: “stable”,
description:
“Launch the Codex desktop app on macOS, optionally opening a specific workspace path.”,
},
{
key: “codex debug app-server send-message-v2”,
href: “/codex/cli/reference#codex-debug-app-server-send-message-v2”,
type: “experimental”,
description:
“Debug app-server by sending a single V2 message through the built-in test client.”,
},
{
key: “codex apply”,
href: “/codex/cli/reference#codex-apply”,
type: “stable”,
description:
“Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: codex a.”,
},
{
key: “codex cloud”,
href: “/codex/cli/reference#codex-cloud”,
type: “experimental”,
description:
“Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: codex cloud-tasks.”,
},
{
key: “codex completion”,
href: “/codex/cli/reference#codex-completion”,
type: “stable”,
description:
“Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.”,
},
{
key: “codex features”,
href: “/codex/cli/reference#codex-features”,
type: “stable”,
description:
“List feature flags and persistently enable or disable them in config.toml.”,
},
{
key: “codex exec”,
href: “/codex/cli/reference#codex-exec”,
type: “stable”,
description:
“Run Codex non-interactively. Alias: codex e. Stream results to stdout or JSONL and optionally resume previous sessions.”,
},
{
key: “codex execpolicy”,
href: “/codex/cli/reference#codex-execpolicy”,
type: “experimental”,
description:
“Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.”,
},
{
key: “codex login”,
href: “/codex/cli/reference#codex-login”,
type: “stable”,
description:
“Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.”,
},
{
key: “codex logout”,
href: “/codex/cli/reference#codex-logout”,
type: “stable”,
description: “Remove stored authentication credentials.”,
},
{
key: “codex mcp”,
href: “/codex/cli/reference#codex-mcp”,
type: “experimental”,
description:
“Manage Model Context Protocol servers (list, add, remove, authenticate).”,
},
{
key: “codex mcp-server”,
href: “/codex/cli/reference#codex-mcp-server”,
type: “experimental”,
description:
“Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.”,
},
{
key: “codex resume”,
href: “/codex/cli/reference#codex-resume”,
type: “stable”,
description:
“Continue a previous interactive session by ID or resume the most recent conversation.”,
},
{
key: “codex fork”,
href: “/codex/cli/reference#codex-fork”,
type: “stable”,
description:
“Fork a previous interactive session into a new thread, preserving the original transcript.”,
},
{
key: “codex sandbox”,
href: “/codex/cli/reference#codex-sandbox”,
type: “experimental”,
description:
“Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline).”,
},
];
export const execOptions = [
{
key: “PROMPT”,
type: “string | - (read stdin)”,
description:
“Initial instruction for the task. Use - to pipe the prompt from stdin.”,
},
{
key: “—image, -i”,
type: “path[,path…]”,
description:
“Attach images to the first message. Repeatable; supports comma-separated lists.”,
},
{
key: “—model, -m”,
type: “string”,
description: “Override the configured model for this run.”,
},
{
key: “—oss”,
type: “boolean”,
defaultValue: “false”,
description:
“Use the local open source provider (requires a running Ollama instance).”,
},
{
key: “—sandbox, -s”,
type: “read-only | workspace-write | danger-full-access”,
description:
“Sandbox policy for model-generated commands. Defaults to configuration.”,
},
{
key: “—profile, -p”,
type: “string”,
description: “Select a configuration profile defined in config.toml.”,
},
{
key: “—full-auto”,
type: “boolean”,
defaultValue: “false”,
description:
“Apply the low-friction automation preset (workspace-write sandbox and on-request approvals).”,
},
{
key: “—dangerously-bypass-approvals-and-sandbox, —yolo”,
type: “boolean”,
defaultValue: “false”,
description:
“Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.”,
},
{
key: “—cd, -C”,
type: “path”,
description: “Set the workspace root before executing the task.”,
},
{
key: “—skip-git-repo-check”,
type: “boolean”,
defaultValue: “false”,
description:
“Allow running outside a Git repository (useful for one-off directories).”,
},
{
key: “—ephemeral”,
type: “boolean”,
defaultValue: “false”,
description: “Run without persisting session rollout files to disk.”,
},
{
key: “—output-schema”,
type: “path”,
description:
“JSON Schema file describing the expected final response shape. Codex validates tool output against it.”,
},
{
key: “—color”,
type: “always | never | auto”,
defaultValue: “auto”,
description: “Control ANSI color in stdout.”,
},
{
key: “—json, —experimental-json”,
type: “boolean”,
defaultValue: “false”,
description:
“Print newline-delimited JSON events instead of formatted text.”,
},
{
key: “—output-last-message, -o”,
type: “path”,
description:
“Write the assistant’s final message to a file. Useful for downstream scripting.”,
},
{
key: “Resume subcommand”,
type: “codex exec resume [SESSION_ID]”,
description:
“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.”,
},
{
key: “-c, —config”,
type: “key=value”,
description:
“Inline configuration override for the non-interactive run (repeatable).”,
},
];
export const appServerOptions = [
{
key: “—listen”,
type: “stdio:// | ws://IP:PORT”,
defaultValue: “stdio://”,
description:
“Transport listener URL. ws:// is experimental and intended for development/testing.”,
},
];
export const appOptions = [
{
key: “PATH”,
type: “path”,
defaultValue: ”.”,
description:
“Workspace path to open in Codex Desktop (codex app is available on macOS only).”,
},
{
key: “—download-url”,
type: “url”,
description:
“Advanced override for the Codex desktop DMG download URL used during install.”,
},
];
export const debugAppServerSendMessageV2Options = [ { key: “USER_MESSAGE”, type: “string”, description: “Message text sent to app-server through the built-in V2 test-client flow.”, }, ];
export const resumeOptions = [
{
key: “SESSION_ID”,
type: “uuid”,
description:
“Resume the specified session. Omit and use --last to continue the most recent session.”,
},
{
key: “—last”,
type: “boolean”,
defaultValue: “false”,
description:
“Skip the picker and resume the most recent conversation from the current working directory.”,
},
{
key: “—all”,
type: “boolean”,
defaultValue: “false”,
description:
“Include sessions outside the current working directory when selecting the most recent session.”,
},
];
export const featuresOptions = [
{
key: “List subcommand”,
type: “codex features list”,
description:
“Show known feature flags, their maturity stage, and their effective state.”,
},
{
key: “Enable subcommand”,
type: “codex features enable config.toml. Respects the active --profile when provided.”,
},
{
key: “Disable subcommand”,
type: “codex features disable config.toml. Respects the active --profile when provided.”,
},
];
export const execResumeOptions = [
{
key: “SESSION_ID”,
type: “uuid”,
description:
“Resume the specified session. Omit and use --last to continue the most recent session.”,
},
{
key: “—last”,
type: “boolean”,
defaultValue: “false”,
description:
“Resume the most recent conversation from the current working directory.”,
},
{
key: “—all”,
type: “boolean”,
defaultValue: “false”,
description:
“Include sessions outside the current working directory when selecting the most recent session.”,
},
{
key: “—image, -i”,
type: “path[,path…]”,
description:
“Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.”,
},
{
key: “PROMPT”,
type: “string | - (read stdin)”,
description:
“Optional follow-up instruction sent immediately after resuming.”,
},
];
export const forkOptions = [
{
key: “SESSION_ID”,
type: “uuid”,
description:
“Fork the specified session. Omit and use --last to fork the most recent session.”,
},
{
key: “—last”,
type: “boolean”,
defaultValue: “false”,
description:
“Skip the picker and fork the most recent conversation automatically.”,
},
{
key: “—all”,
type: “boolean”,
defaultValue: “false”,
description:
“Show sessions beyond the current working directory in the picker.”,
},
];
export const execpolicyOptions = [ { key: “—rules, -r”, type: “path (repeatable)”, description: “Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.”, }, { key: “—pretty”, type: “boolean”, defaultValue: “false”, description: “Pretty-print the JSON result.”, }, { key: “COMMAND…”, type: “var-args”, description: “Command to be checked against the specified policies.”, }, ];
export const loginOptions = [
{
key: “—with-api-key”,
type: “boolean”,
description:
“Read an API key from stdin (for example printenv OPENAI_API_KEY | codex login --with-api-key).”,
},
{
key: “—device-auth”,
type: “boolean”,
description:
“Use OAuth device code flow instead of launching a browser window.”,
},
{
key: “status subcommand”,
type: “codex login status”,
description:
“Print the active authentication mode and exit with 0 when logged in.”,
},
];
export const applyOptions = [ { key: “TASK_ID”, type: “string”, description: “Identifier of the Codex Cloud task whose diff should be applied.”, }, ];
export const sandboxMacOptions = [
{
key: “—full-auto”,
type: “boolean”,
defaultValue: “false”,
description:
“Grant write access to the current workspace and /tmp without approvals.”,
},
{
key: “—config, -c”,
type: “key=value”,
description:
“Pass configuration overrides into the sandboxed run (repeatable).”,
},
{
key: “COMMAND…”,
type: “var-args”,
description:
“Shell command to execute under macOS Seatbelt. Everything after -- is forwarded.”,
},
];
export const sandboxLinuxOptions = [
{
key: “—full-auto”,
type: “boolean”,
defaultValue: “false”,
description:
“Grant write access to the current workspace and /tmp inside the Landlock sandbox.”,
},
{
key: “—config, -c”,
type: “key=value”,
description:
“Configuration overrides applied before launching the sandbox (repeatable).”,
},
{
key: “COMMAND…”,
type: “var-args”,
description:
“Command to execute under Landlock + seccomp. Provide the executable after --.”,
},
];
export const completionOptions = [ { key: “SHELL”, type: “bash | zsh | fish | power-shell | elvish”, defaultValue: “bash”, description: “Shell to generate completions for. Output prints to stdout.”, }, ];
export const cloudExecOptions = [
{
key: “QUERY”,
type: “string”,
description:
“Task prompt. If omitted, Codex prompts interactively for details.”,
},
{
key: “—env”,
type: “ENV_ID”,
description:
“Target Codex Cloud environment identifier (required). Use codex cloud to list options.”,
},
{
key: “—attempts”,
type: “1-4”,
defaultValue: “1”,
description:
“Number of assistant attempts (best-of-N) Codex Cloud should run.”,
},
];
export const cloudListOptions = [ { key: “—env”, type: “ENV_ID”, description: “Filter tasks by environment identifier.”, }, { key: “—limit”, type: “1-20”, defaultValue: “20”, description: “Maximum number of tasks to return.”, }, { key: “—cursor”, type: “string”, description: “Pagination cursor returned by a previous request.”, }, { key: “—json”, type: “boolean”, defaultValue: “false”, description: “Emit machine-readable JSON instead of plain text.”, }, ];
export const mcpCommands = [
{
key: “list”,
type: “—json”,
description:
“List configured MCP servers. Add --json for machine-readable output.”,
},
{
key: “get --json prints the raw config entry.”,
},
{
key: “add --env KEY=VALUE for stdio transports.”,
},
{
key: “remove
export const mcpAddOptions = [
{
key: “COMMAND…”,
type: “stdio transport”,
description:
“Executable plus arguments to launch the MCP server. Provide after --.”,
},
{
key: “—env KEY=VALUE”,
type: “repeatable”,
description:
“Environment variable assignments applied when launching a stdio server.”,
},
{
key: “—url”,
type: “https://…”,
description:
“Register a streamable HTTP server instead of stdio. Mutually exclusive with COMMAND....”,
},
{
key: “—bearer-token-env-var”,
type: “ENV_VAR”,
description:
“Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.”,
},
];
How to read this reference
Section titled “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
Section titled “Global flags”<ConfigTable client:load options={globalFlagOptions} />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
Section titled “Command overview”The Maturity column uses feature maturity labels such as Experimental, Beta, and Stable. See Feature Maturity for how to interpret these labels.
<ConfigTable client:load options={commandOverview} secondColumnTitle="Maturity" secondColumnVariant="maturity"/>Command details
Section titled “Command details”codex (interactive)
Section titled “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
Section titled “codex app-server”Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.
<ConfigTable client:load options={appServerOptions} />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
Section titled “codex app”Launch Codex Desktop from the terminal on macOS and optionally open a specific workspace path.
<ConfigTable client:load options={appOptions} />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
Section titled “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.
<ConfigTable client:load options={debugAppServerSendMessageV2Options} />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
Section titled “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.
<ConfigTable client:load options={applyOptions} />Codex prints the patched files and exits non-zero if git apply fails (for example, due to conflicts).
codex cloud
Section titled “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.
<ConfigTable client:load options={cloudExecOptions} />Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.
codex cloud list
Section titled “codex cloud list”List recent cloud tasks with optional filtering and pagination.
<ConfigTable client:load options={cloudListOptions} />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
Section titled “codex completion”Generate shell completion scripts and redirect the output to the appropriate location, for example codex completion zsh > "${fpath[1]}/_codex".
<ConfigTable client:load options={completionOptions} />codex features
Section titled “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.
<ConfigTable client:load options={featuresOptions} />codex exec
Section titled “codex exec”Use codex exec (or the short form codex e) for scripted or CI-style runs that should finish without human interaction.
<ConfigTable client:load options={execOptions} />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:
<ConfigTable client:load options={execResumeOptions} />codex execpolicy
Section titled “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.
<ConfigTable client:load options={execpolicyOptions} />codex login
Section titled “codex login”Authenticate the CLI with a ChatGPT account or API key. With no flags, Codex opens a browser for the ChatGPT OAuth flow.
<ConfigTable client:load options={loginOptions} />codex login status exits with 0 when credentials are present, which is helpful in automation scripts.
codex logout
Section titled “codex logout”Remove saved credentials for both API key and ChatGPT authentication. This command has no flags.
codex mcp
Section titled “codex mcp”Manage Model Context Protocol server entries stored in ~/.codex/config.toml.
<ConfigTable client:load options={mcpCommands} />The add subcommand supports both stdio and streamable HTTP transports:
<ConfigTable client:load options={mcpAddOptions} />OAuth actions (login, logout) only work with streamable HTTP servers (and only when the server supports OAuth).
codex mcp-server
Section titled “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
Section titled “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.
<ConfigTable client:load options={resumeOptions} />codex fork
Section titled “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.
<ConfigTable client:load options={forkOptions} />codex sandbox
Section titled “codex sandbox”Use the sandbox helper to run a command under the same policies Codex uses internally.
macOS seatbelt
Section titled “macOS seatbelt”<ConfigTable client:load options={sandboxMacOptions} />Linux Landlock
Section titled “Linux Landlock”<ConfigTable client:load options={sandboxLinuxOptions} />Flag combinations and safety tips
Section titled “Flag combinations and safety tips”- Set
--full-autofor unattended local work, but avoid combining it with--dangerously-bypass-approvals-and-sandboxunless you are inside a dedicated sandbox VM. - When you need to grant Codex write access to more directories, prefer
--add-dirrather than forcing--sandbox danger-full-access. - Pair
--jsonwith--output-last-messagein CI to capture machine-readable progress and a final natural-language summary.
Related resources
Section titled “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.