Cheat Sheet: CLI Flags & Subcommands

Before the tables, fix the map in your head, because every flag below hangs off it. The Codex CLI is one root command, codex, that branches two ways:

• Subcommands answer what you're doing: start an interactive session, run a headless task (exec), resume a thread, sign in, delegate to the cloud, manage MCP servers, run diagnostics. You pick exactly one subcommand per invocation (or none — bare codex launches the interactive TUI).
• Global flags answer how it behaves: which model, which sandbox, when to ask for approval, which directory, which config overrides. Most global flags apply to codex and propagate to subcommands like exec.

Sitting across the top are two independent controls that you'll meet again and again:

• --sandbox / -s = WHERE Codex may read, write, and reach the network (an OS-enforced boundary).
• --ask-for-approval / -a = WHEN Codex must stop and ask a human.

They are related but not interchangeable — you set them separately, and the lesson on approvals goes deep on the combinations. Here we just catalog the values.

One discipline runs through this whole reference: Codex is fast-moving. Model names, the default model, the exact slash-command roster, per-plan limits, and the CLI version all rot. Where a value is volatile, this lesson teaches the concept and points you at the live page rather than freezing a number that will be wrong next month.

All channels install the same codex binary — the open-source CLI written in Rust. Pick by platform and preference.

# npm (Node ≥ 16) — cross-platform
npm install -g @openai/codex     # SCOPED package; bare "codex" on npm is unrelated — do not install it

# Homebrew (macOS) — note it is a CASK
brew install --cask codex

# Standalone installer (macOS / Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Standalone installer (Windows PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

• Unattended installs: set CODEX_NON_INTERACTIVE=1 before the script.
• Install target: CODEX_INSTALL_DIR overrides it (default ~/.local/bin; %LOCALAPPDATA%\Programs\OpenAI\Codex\bin on Windows).
• Update: there is no separate updater — run codex update (a built-in subcommand) to check for and apply CLI updates.
• Supported OS: macOS (Apple Silicon + Intel), Linux (x86_64 + arm64), Windows native (PowerShell sandbox) or WSL2. WSL1 was dropped at CLI 0.115 when the Linux sandbox moved to bubblewrap.

Run one of these after codex (or none, to launch the interactive TUI). Stability and exact flags evolve — the canonical reference is https://developers.openai.com/codex/cli/reference.

codex vs codex exec is the split that matters most. Bare codex is interactive (a full-screen TUI). codex exec (alias e) is headless: it streams progress to stderr and prints only the final agent message to stdout (or JSONL events with --json), so RESULT="$(codex exec '...')" captures just the answer. Its default sandbox is read-only — opt into --sandbox workspace-write to let it edit files.

These apply to codex and propagate to most subcommands. PROMPT itself is an optional positional argument.

Feature / search / connection flags:

Note the difference: -c KEY=VALUE overrides a config key for one run; --enable/--disable toggles a named feature flag; --profile swaps in a whole overlay file. They compose — the precedence is CLI flags & -c overrides on top, then project config, then the profile, then user config.

This is the pair people most often confuse. They are two independent controls: the sandbox is the OS-enforced boundary (WHERE), the approval policy is the human-pause rule (WHEN). You set them separately, and either can be tight while the other is loose.

--sandbox / -s (or sandbox_mode in config) — WHERE:

--ask-for-approval / -a (or approval_policy) — WHEN:

The TUI bundles common pairings into presets: Read Only = read-only + on-request; Auto (the everyday default) = workspace-write + on-request; Full Access = danger-full-access + no approvals ("not recommended"). Note that on-failure is deprecated as an approval value.

Enforcement is real OS sandboxing: macOS Seatbelt (sandbox-exec); Linux/WSL2 bubblewrap + seccomp (with Landlock fallback); Windows native sandbox via PowerShell. If the platform can't enforce the policy, Codex refuses to run rather than run unsandboxed.

Two more flags remove safety at once. Know them so you recognize them in someone else's command and never paste them blindly.

--yolo is the single most dangerous flag in the CLI: it is the union of danger-full-access (WHERE = everywhere) and never approvals (WHEN = never asks). Because sandboxing is Codex's primary defense against prompt injection — it's what stops a malicious instruction in a web page or MCP response from doing real damage — bypassing it means a single poisoned input can run arbitrary commands with your privileges.

If you genuinely need unattended autonomy, prefer the narrow tools: --add-dir to widen writes, config network opt-in for connectivity, and a real container around the whole thing. There is also no --undo and no /undo — rollback is your normal git workflow, because Codex surfaces every action in the transcript. Plan your escape hatch (a clean branch, committed state) before you loosen anything.

A few interactive shortcuts trip people up because they differ from other agent CLIs. Get these exactly right:

State & logs live under CODEX_HOME (default ~/.codex/): config.toml, auth.json, sessions/, archived_sessions/, and log/ (codex-tui.log). Set RUST_LOG (error|warn|info|debug|trace, or targeted like codex_core=debug,codex_tui=debug) for verbose logging. The agent's project instructions live in AGENTS.md (Codex's cross-tool standard — not CLAUDE.md); scaffold one with /init.

For the in-session slash commands, the roster is large and evolving — type / to see the live popup, and treat https://developers.openai.com/codex/cli/slash-commands as canonical. Two corrections worth memorizing: the old /approvals is now /permissions, and /undo does not exist.