The Codex CLI is OpenAI's coding agent for the terminal: you install it with one command, run codex in a project, and steer it with slash commands such as /model, /permissions, /review and /subagents. For scripts and CI you use codex exec, and the "Auto" preset (workspace writes, approval for anything outside) is the default for Git repositories. This cheat sheet covers the commands we actually use, checked against the official docs and the installed CLI (version 0.167.1, the latest on npm as of November 11, 2026).
Codex changes almost weekly, so every section links to the source. If something here disagrees with codex --help on your machine, trust your machine and update.
Install the Codex CLI (macOS, Linux, Windows)
The openai/codex README lists a standalone installer as the main option, with npm and Homebrew as alternatives:
# macOS and Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
# npm (any OS with Node.js)
npm install -g @openai/codex
# Homebrew
brew install --cask codexThe GitHub releases page also has prebuilt binaries (for example codex-aarch64-apple-darwin.tar.gz for Apple Silicon). On Windows, OpenAI also documents running Codex inside WSL and a separate Windows sandbox.
On first run, choose Sign in with ChatGPT to use the Codex allowance in your ChatGPT plan, or set up API-key sign-in. For API keys in CI, the non-interactive docs show setting CODEX_API_KEY inline for a single run and warn against putting OPENAI_API_KEY or CODEX_API_KEY in a job-level environment where repository code runs. If you'd rather keep real keys out of shell profiles altogether, that's the problem our EnvSave vault solves (opaque es_ keys instead of the secret); the same idea for Claude Code is covered in our Claude Code API key guide.
Update the Codex CLI
The CLI reference describes codex update as "Check for and apply a Codex CLI update when the installed release supports self-update." If you installed through a package manager, update the way you installed:
codex update # standalone installer builds
npm install -g @openai/codex@latest # npm
brew upgrade --cask codex # Homebrew
codex --version # confirm, e.g. codex-cli 0.167.1
codex doctor # diagnose install, config, auth, runtimecodex doctor is worth knowing: it writes a diagnostic report of the installation, config and auth, and codex doctor --json emits a redacted machine-readable version you can paste into a bug report.
Top-level Codex CLI commands
This is the real codex --help command list from 0.167.1, trimmed to the commands most people need:
Commands:
agents Open the agent command center to browse and switch sessions
exec Run Codex non-interactively [aliases: e]
review Run a code review non-interactively
login Manage login
mcp Manage external MCP servers for Codex
plugin Manage Codex plugins
remote-control [experimental] Manage the app-server daemon with remote control enabled
app Launch the Desktop app (opens the app installer if missing)
update Update Codex to the latest version
doctor Diagnose local Codex installation, config, auth, and runtime health
sandbox Run commands within a Codex-provided sandbox
apply Apply the latest diff produced by Codex agent as a `git apply` ...
resume Resume a previous interactive session (picker by default; use --last ...)
fork Fork a previous interactive session (picker by default; use --last ...)
cloud [EXPERIMENTAL] Browse tasks from Codex Cloud and apply changes locally
features Inspect feature flagsUseful global flags: -m (model), -s (sandbox), -a (approval policy), -C (working directory), --add-dir (extra writable directory), --worktree (run in a new managed Git worktree), --search (live web search), -i (attach an image) and -p (profile).
Codex CLI slash commands cheat sheet
Type / in the composer to see the full popup. The list below uses the descriptions from the CLI's own source (slash_command.rs), and we confirmed each one ships in 0.167.1. The slash commands reference has the rest.
| Command | What it does |
|---|---|
/model | Choose the model and reasoning effort |
/permissions | Choose what Codex is allowed to do (switch between Auto, read-only and full access) |
/status | Show current session configuration and token usage |
/init | Create an AGENTS.md file with instructions for Codex |
/plan | Switch to Plan mode |
/goal | Set or view the goal for a long-running task |
/review | Review your current changes and find issues |
/diff | Show git diff, including untracked files |
/compact | Summarize the conversation to avoid hitting the context limit |
/new, /resume, /fork | Start a new chat, resume a saved one, or fork the current one |
/side (or /btw) | Start a side conversation without derailing the main task |
/subagents | Switch between this session's subagents |
/agents | Open the agent command center |
/mcp | List MCP tools (/mcp verbose, /mcp login <name>) |
/skills | Use skills to improve how Codex performs specific tasks |
/import | Import setup, this project and recent chats from Claude Code |
/app | Continue this session in the desktop app |
/usage | View account usage |
/mention | Mention a file |
/quit or /exit | Exit Codex |
codex exec: non-interactive runs for scripts and CI
codex exec (alias codex e) runs one task and exits. According to the non-interactive mode docs, it runs in a read-only sandbox by default, progress goes to stderr and only the final agent message goes to stdout, so you can pipe it:
# read-only analysis
codex exec "summarize the repository structure and list the top 5 risky areas"
# allow edits inside the workspace
codex exec --sandbox workspace-write "fix the failing unit tests"
# pipe input in, capture the answer
npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix" | tee test-summary.md
# machine-readable: JSON Lines events + structured final answer
codex exec --json "summarize the repo structure" | jq
codex exec "Extract project metadata" --output-schema ./schema.json -o ./project-metadata.json
# continue the last run
codex exec resume --last "now add tests for the fix"Other flags from codex exec --help worth knowing: --ephemeral (don't save session files), --skip-git-repo-check (run outside a Git repo), --ignore-user-config, and -o / --output-last-message. For pull-request reviews there is also codex review --uncommitted or codex review --base main. Note that --full-auto, which older tutorials use, is no longer supported.
Codex CLI auto mode: sandbox and approval settings
"Auto mode" in Codex is two settings working together: a sandbox (what commands can technically touch) and an approval policy (when Codex stops to ask). The approvals and security docs describe them as follows:
| Mode | Flags | Behavior |
|---|---|---|
| Auto (preset) | --sandbox workspace-write --ask-for-approval on-request | Edits and commands run without asking inside the workspace (current directory plus temp dirs). Edits outside it and network access need approval. .git, .agents, .codex and .aws stay read-only. |
| Read-only | --sandbox read-only | Codex can read and plan but not change files. Recommended for folders that aren't under version control. |
| Auto-review | --approve-for-me or approvals_reviewer = "auto_review" | Same workspace-write sandbox, but eligible approval requests go to a reviewer agent instead of you. /approve lets you approve one retry of a recent auto-review denial. |
| Full access | --dangerously-bypass-approvals-and-sandbox (alias --yolo) | No sandbox and no approvals. Only for environments that are already isolated, such as a disposable container. |
Two details that trip people up. First, network access is off in Auto; to allow it, set sandbox_workspace_write.network_access = true. Second, the old untrusted approval policy is retired, and the docs warn that leaving it in a config can stop Codex from starting. The current policies are on-request, never and granular.
AGENTS.md: project instructions
Codex reads AGENTS.md files as standing instructions (AGENTS.md docs):
- Global:
~/.codex/AGENTS.override.mdif present, otherwise~/.codex/AGENTS.md(or underCODEX_HOME). - Project: from the Git root down to your current directory, at most one file per directory, checking
AGENTS.override.md, thenAGENTS.md, then any names inproject_doc_fallback_filenames. - Merge: files are joined root-first, so the file closest to where you work wins on conflicts.
- Limit: loading stops at
project_doc_max_bytes, 32 KiB by default.
Run /init to generate a first draft, then cut it down to the commands, conventions and "never do this" rules a new teammate would need. For how AGENTS.md compares with Claude Code's files and skills, see skills vs agents vs AGENTS.md.
config.toml essentials
User settings live in ~/.codex/config.toml; a project can add .codex/config.toml, which Codex loads only once you trust the project. CLI flags and -c key=value beat project config, which beats profiles, which beat your user config (config basics). The CLI and the IDE extension share these layers. A starting point built only from documented keys:
# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached" # cached | indexed | live | disabled
[sandbox_workspace_write]
network_access = false # true lets sandboxed commands reach the network
[agents]
max_concurrent_threads_per_session = 4
[features]
memories = falseProfiles are separate files: ~/.codex/review.config.toml is layered on top when you run codex -p review. To see which feature flags your build has, run codex features list; on 0.167.1 it shows, among others:
goals stable true
hooks stable true
memories stable false
multi_agent stable true
multi_agent_v2 stable falseCodex CLI subagents
Yes, Codex has subagents, and they're on by default (multi_agent above). Per the subagents docs, Codex can spawn specialized agents that work in parallel and report back in one consolidated answer. You trigger them by asking ("spawn one agent per module and wait for all of them"), or through an AGENTS.md or skill instruction. Built-in types are default, worker (implementation and fixes) and explorer (read-heavy exploration). In the CLI, /subagents switches between their threads, and if an inactive thread asks for approval you can press o to open it.
Custom agents are one TOML file each, in ~/.codex/agents/ or the project's .codex/agents/. Required fields are name, description and developer_instructions:
# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, and missing test coverage.
"""Limits to plan around: subagents inherit the parent's sandbox, approval policy, model provider and MCP servers (you can't loosen them per agent), and OpenAI recommends them for read-heavy work, since parallel writers can collide. If you need agents that each have their own folder, brief and lifetime, that's a swarm rather than subagents; we compare the two for Claude Code in agent teams vs swarms.
Codex CLI remote control
There are two different things called "remote" here:
- Phone control via the ChatGPT app. The remote connections docs describe pairing your phone with a Mac or Windows host from the ChatGPT desktop app (Settings > Connections > Control this Mac or PC, then scan a QR code). From the phone you can start chats, approve actions and review diffs. The docs say plainly: "Mobile setup starts from the app; you can't set it up from the Codex CLI or IDE extension." The desktop app can also open projects on SSH hosts, which requires
codexon the remote host's PATH. codex remote-controlin the CLI. Marked experimental. It starts or stops a local app-server daemon with remote control enabled, andpairprints a short-lived manual pairing code (--jsonreturnspairingCode,environmentIdandexpiresAt). Separately, the global--remote ws://host:portflag connects the CLI's interface to a remote app-server.
$ codex remote-control --help
[experimental] Manage the app-server daemon with remote control enabled
Commands:
start Start the app-server daemon with remote control enabled
stop Stop the app-server daemon
pair Create and print a short-lived manual pairing codeCodex CLI vs Codex app vs IDE extension
All three run the same agent. The desktop experience now lives in the ChatGPT desktop app (codex app launches it; the app docs describe choosing ChatGPT or Codex inside it). The IDE extension covers VS Code, Cursor, Windsurf and VS Code Insiders.
| Codex CLI | Desktop app | IDE extension | |
|---|---|---|---|
| Where it runs | Any terminal (macOS, Linux, Windows) | ChatGPT desktop app (macOS, Windows; Linux per the quickstart) | VS Code, Cursor, Windsurf, VS Code Insiders |
| Best for | Terminal work, scripting and CI with codex exec | Several projects in parallel, long-running work, scheduled tasks, computer use | Working beside the code with open files and selections as context |
| Subagents | Yes, /subagents | Yes, as separate threads | Yes, shown above the composer |
| Phone remote control | Not set up from here (experimental codex remote-control daemon) | Yes, set up here | Not set up from here |
| Config | config.toml layers | App settings | Same layers as the CLI |
| Handoff | /app continues the session in the app | Hand off chats between hosts | Send longer tasks to Codex web |
Rule of thumb: if you want to script it or run it on a server, use the CLI. If you want to watch several long tasks or reach them from your phone, use the app. If you live in an editor, use the extension.
Running Codex next to Claude Code on the same project
Plenty of teams use both: Codex for some tasks, Claude Code for others. A few things make that painless:
- One instruction file. Codex reads
AGENTS.md. Claude Code (v2.1.277 and later) reads AGENTS.md too, but only when there's noCLAUDE.md. If you keep aCLAUDE.md, importAGENTS.mdfrom it so both agents follow the same rules. - Separate working copies. Two agents editing one checkout will step on each other. Give Codex its own worktree with
codex --worktree, or a separate branch. - Clear roles. For example, Codex builds and Claude Code reviews, or the reverse.
codex review --base mainalso works as a second opinion on Claude's branch.
If you want this as a coordinated team instead of two terminals you switch between, our open-source Hivey runs mixed swarms. Each agent gets its own folder and brief, and --kinds chooses the CLI per agent. Codex agents read AGENTS.md, which Hivey links to the agent's CLAUDE.md. From hivey swarm launch --help:
usage: hivey swarm launch <root> --slug SLUG <agent>... [--models a=sonnet,...]
[--kinds a=codex,b=grok,c=agy] [--claude-args|--codex-args|... "..."]
Starts one coding agent per agent in <root>/<agent>/ (CLAUDE.md required) as <slug>-<agent>:
Claude Code by default, or Codex, Grok or Antigravity (agy, Gemini) with --kinds; the others
read CLAUDE.md through an AGENTS.md (and, for agy, GEMINI.md) link.
# e.g. a Codex builder reviewed by a Claude Code critic
hivey swarm launch ./myapp-swarm --slug myapp builder critic --kinds builder=codexOne thing to know: by default Hivey starts agents without approval prompts, so pass your own sandbox flags with --codex-args if you want Codex in Auto or read-only mode inside a swarm.
Next steps
Install, run /init, set a config.toml with the sandbox you're comfortable with, and try one codex exec job in CI before you give an agent write access to anything important. If you'd like help designing an agent workflow for your team, mixing Codex, Claude Code or both, get in touch.