The complete guide to Codex CLI

Codex CLI is OpenAI’s coding agent for the terminal. You run codex inside a repository, describe what you want, and it reads the tree, edits files, and runs commands — tests, builds, git — inside an operating-system sandbox on the machine it is installed on, stopping to ask before it steps outside the boundaries you set. It is a Rust binary, open source under Apache-2.0, and it signs in with the ChatGPT account you already pay for. On 3 September 2026 the current release is 0.153.0; it ships several times a week, so everything here is checked against that version and the vendor’s docs on that date.

The name covers four surfaces, and a search for “codex cli” often means one of the other three. Codex cloud runs tasks in OpenAI-hosted, isolated environments against a GitHub or GitLab repository you connect; you dispatch from chatgpt.com/codex or from the CLI with codex cloud, and results come back as pull requests or diffs you can pull down with codex apply. The IDE extension works beside the code in VS Code, Cursor, and Windsurf, with native integrations for Xcode and JetBrains, and can hand longer work off to the cloud. The desktop app on macOS, Windows, and Linux is the visual, project-based face of the same agent. The CLI is the one that runs where your checkout, your toolchain, and your credentials already live — and it is the one this guide is about.

There are four official routes, and they all install the same binary. On macOS and Linux the standalone installer — curl -fsSL https://chatgpt.com/codex/install.sh | sh — puts codex in ~/.local/bin and adds it to your shell profile; running the same line again updates it. Windows has an equivalent PowerShell installer and a native sandbox, so WSL2 is a choice rather than a requirement. npm install -g @openai/codex works on all three platforms because the package carries a prebuilt binary for each, and brew install --cask codex is the Homebrew route. Whichever you pick, codex --version confirms it and codex update moves it forward when the installed release supports self-update. The install guide walks each platform step by step, including native Windows versus WSL2.

The first codex run asks how to sign in. “Sign in with ChatGPT” opens a browser and ties the CLI to your plan: the pricing page ticks the CLI for Plus, Pro, Business, and Enterprise or Edu — Free and Go include Codex in ChatGPT but not in the CLI row of that table. Usage on a ChatGPT plan is a rolling five-hour window shared between local messages and cloud chats, with weekly limits on top, and Plus and Pro can buy credits when the window runs dry. The alternative is an API key: codex login --with-api-key reads the key from stdin, bills per token at API rates, and loses the features that depend on ChatGPT workspace access or the cloud. On a headless box, codex login --device-auth gives you a code to enter elsewhere, or forward the callback port with ssh -L 1455:localhost:1455 user@host and sign in through your laptop’s browser. Whatever you choose, the result is ~/.codex/auth.json, which the auth docs say to treat like a password.

Codex has two independent dials, and knowing they are independent is most of understanding its safety model. The sandbox is what the operating system lets a command do; the approval policy is when Codex stops to ask you. Both live in config.toml and both can be set per run.

Sandbox modes are three. read-only lets the agent inspect files but not edit them or run commands without approval. workspace-write, the default, lets it read anywhere, edit inside the working directory plus any writable_roots you add and the system temp directories, and run ordinary local commands within that boundary — with no outbound network unless you set network_access = true under [sandbox_workspace_write], and with .git and .codex protected from writes. danger-full-access removes the boundary entirely. Underneath, macOS uses Seatbelt; Linux and WSL2 use bubblewrap (since 0.115, which is also when WSL1 support ended); Windows has a native sandbox in two strengths — elevated, which sets up dedicated low-privilege sandbox users and firewall rules, and unelevated, which runs commands under a restricted token derived from your own user.

Approval policies are untrusted (only known-safe read operations run without asking), on-request (the model asks when it wants to step outside the sandbox — edit elsewhere, reach the network), and never. The presets in /permissions are combinations: Auto is workspace-write plus on-request and is the default in a version-controlled folder; Read-only pairs read-only with on-request; Dangerous full access is danger-full-access with no approvals, also reachable as --dangerously-bypass-approvals-and-sandbox or its alias --yolo. The older --full-auto flag is deprecated but still accepted. Per run, --sandbox (-s) and --ask-for-approval (-a) set the two dials directly, and codex exec, the non-interactive mode, defaults to read-only. Newer builds also expose permission profiles — :read-only, :workspace, :danger-full-access, selected with default_permissions — which replace sandbox_mode when used; the docs say to configure one system or the other, not both.

Personal defaults live in ~/.codex/config.toml; a trusted project can add .codex/config.toml at its root; Unix systems can carry /etc/codex/config.toml. Precedence runs from command-line flags and -c key=value overrides, through project files, then a profile, then the user file, then the system file, down to built-in defaults. A profile is a file named ~/.codex/<name>.config.toml, selected with --profile <name> (-p), and it is how one machine keeps a locked-down profile for unfamiliar repos beside a permissive one for your own. The reference lists every key; the ones that matter daily are model, model_reasoning_effort (minimal through xhigh), approval_policy, sandbox_mode, the [sandbox_workspace_write] table, web_search (disabled, cached, indexed, or live), notify for a command to run when Codex wants you, [history] persistence (save-all or none), and [projects."/path"] trust_level.

Models are chosen with /model inside a session, -m on the command line, or model = "gpt-5.6" in the file; the same command sets reasoning effort. MCP servers are [mcp_servers.<name>] tables — command, args, and env for a stdio server, url and bearer_token_env_var for an HTTP one — with startup_timeout_sec (default 10), tool_timeout_sec (default 60), and enabled = false to park one without deleting it. codex mcp add <name> -- <command> writes the table for you, codex mcp list shows what is configured, codex mcp login <name> handles servers that need OAuth, and /mcp inside a session lists what is live. Project instructions go in AGENTS.md, which /init will draft.

Every chat is saved without being asked. Codex writes a rollout — a JSONL transcript of the conversation, tool calls, and results — under ~/.codex/sessions/YYYY/MM/DD/, one file per thread named rollout-<timestamp>-<thread-id>.jsonl, sometimes compressed to .jsonl.zst. codex resume opens a picker over the chats started from the current directory; codex resume --last skips the picker; --all widens it to every directory; a session id resumes one exactly. codex fork (or /fork inside a session) starts a new thread that inherits the transcript, and codex exec resume --last continues a scripted run. Inside the TUI, /rollout prints the file’s path, /export writes the conversation as markdown, /archive moves the thread to ~/.codex/archived_sessions, and /delete removes it for good.

What the file holds is the conversation, not the process. Resuming reads the transcript into a fresh codex; a command that was half-run when the terminal closed is not picked back up, and a session on one machine is a file on that machine’s disk. The sessions guide goes through the storage, the commands, and where this stops being enough.

The loop most people settle into: cd into the repository, run codex, accept the Auto preset, and describe the task with the acceptance test in the sentence — “make the failing spec in auth_test.go pass without changing the handler’s signature.” Let it run; answer the approval prompts it raises when it wants the network or a path outside the tree. /diff shows what changed, /review has it critique its own work, /status shows the directories in play and token use, /compact summarises a long thread before it hits the context limit, /new starts clean. -i attaches a screenshot to a prompt, --search turns on live web search for the run, and codex exec "…" puts the same agent in a script or a CI job, read-only by default and streaming events with --json.

Against Claude Code the shape is the same — a terminal agent that edits your tree, runs your commands, asks at boundaries, reads a project file (AGENTS.md here, CLAUDE.md there), speaks MCP, and resumes past sessions — so the choice rarely turns on features. It turns on which subscription you already hold, since each CLI draws on its own vendor’s plan; on which model you trust with your codebase; and on two real differences: Codex CLI is open source and Claude Code is not, and Codex’s default is an OS-level sandbox with approvals at its edge, where Claude Code’s default is per-action permission prompts. Plenty of people run both on the same repository and let the results argue. The Claude Code guide covers the other side, and the agents roundup puts them beside OpenCode, Aider, and the rest.

Everything above happens on the machine you typed codex into, which is the whole point and the whole limit. The session is a process in a terminal: close the laptop, lose the SSH connection, or reboot, and the transcript survives but the run does not. Reaching that machine from anywhere else means exposing it — a port, a VPN, a bastion — and keeping SSH keys on every device you might be holding. From a phone, OpenAI’s own answer is the cloud: real and useful, and their container rather than your dev box with your checkouts, your services, and your local state.

spawnd is built for the other half. One daemon on each host you own dials out, so nothing listens on the host — no open ports, no VPN. Each session’s PTY is owned by a worker process on the host, so a Codex run survives the closed tab, the dropped connection, the laptop lid, and a restart of the daemon itself, scrollback intact. Any browser is the console, and on a phone it installs to the home screen as a web app; a new device is approved once against a short code, and revoking it is one click every host honors. Codex is a built-in shortcut — the button types codex into a real login shell on the host, so your sign-in, your config.toml, and your sandbox settings apply exactly as at the keyboard; spawnd holds no provider credentials and adds no API-key markup. Your browser talks to each daemon peer-to-peer, end-to-end encrypted; the server that introduces them never sees session content. Workspaces put one project’s sessions across hosts in one grid, an attention cue marks the session waiting on a yes, and the yes arrives from wherever you are. The sessions guide goes deeper on the run outliving the terminal, and the security page sets out what the server can and cannot see.