Codex CLI guide: install, commands, config, sandbox, skills and MCP

What the Codex CLI is

The Codex CLI is OpenAI’s coding agent for the terminal. It reads your repository, edits files and runs commands inside a sandbox, either in an interactive terminal UI or as a scriptable codex exec command for pipelines. It shares configuration, skills and MCP servers with the Codex IDE extension and Codex in the ChatGPT desktop app, so setup done once carries across.

Install

Platform	Install	Update
macOS, Linux	curl -fsSL https://chatgpt.com/codex/install.sh | sh	Same command
Windows (PowerShell)	powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"	Same command
npm	npm install -g @openai/codex	Same command
Homebrew	brew install --cask codex	brew upgrade --cask codex

codex update also checks for and applies an update when your install supports self-update. On Linux and WSL2, install bubblewrap (sudo apt install bubblewrap or sudo dnf install bubblewrap) so the sandbox works reliably; macOS uses the built-in Seatbelt framework.

Sign in

Run codex in a project directory. On first launch, choose Sign in with ChatGPT or another available method. From a shell:

codex login                     # browser sign-in with your ChatGPT account
codex login --device-auth       # device code flow, for remote machines
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status              # exits 0 when signed in
codex logout

Credentials are stored in ~/.codex/auth.json. Treat it like a password: do not commit it or paste it anywhere.

Your first session

cd ~/src/my-app
git status          # start from a clean tree so you can review and revert
codex

Then ask something low-risk, such as “Tell me about this project”, before asking for edits. Make a git checkpoint before and after a task so every change is easy to review and undo.

Interactive essentials

Slash commands you will use daily:

Command	What it does
/model	Choose the model and, when available, reasoning effort
/permissions	Change what Codex may do without asking
/status	Show the active model, approval policy, writable roots and context usage
/plan	Ask for a plan before implementation
/diff	Show the git diff, including untracked files
/review	Have Codex review your working tree
/init	Generate an AGENTS.md scaffold
/skills	Browse and insert skills
/mcp	List MCP servers and tools (/mcp verbose for detail)
/plugins	Browse and manage plugins
/mention	Attach a file to the conversation
/compact	Summarize the chat to free context
/resume, /new, /fork	Continue an old chat, start fresh, or branch this one

Shortcuts:

• @ searches for a file and inserts its path.
• ! at the start of a line runs a shell command under the current sandbox and approval settings.
• Enter while Codex is working steers the current turn; Tab queues a message for the next turn.
• Esc twice with an empty composer edits your previous message and forks from there.
• Ctrl+R searches prompt history; Ctrl+C or /exit quits.

Flags worth knowing

Flag	Purpose
-m, --model <name>	Override the configured model
-s, --sandbox <mode>	read-only, workspace-write or danger-full-access
-a, --ask-for-approval <policy>	on-request or never
--approve-for-me	workspace-write with on-request approvals routed to automatic review
-C, --cd <dir>	Set the working directory
--add-dir <dir>	Grant write access to another directory (repeatable)
-c, --config key=value	Override any config key for this run
-p, --profile <name>	Layer ~/.codex/<name>.config.toml over your config
-i, --image <path>	Attach images to the first prompt
--search	Use live web search instead of the default cached results
--oss	Use a local open-source model provider (LM Studio or Ollama)
--yolo	No sandbox and no approvals; only inside an isolated VM or container

Scripting with codex exec

codex exec (short form codex e) runs a task without the interactive UI. Progress streams to stderr and only the final message goes to stdout, so it pipes cleanly:

codex exec "summarize the repository structure and list the top 5 risky areas"
codex exec "generate release notes for the last 10 commits" | tee release-notes.md
npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix"
cat prompt.txt | codex exec -

Key behavior:

• Read-only by default. Allow edits with --sandbox workspace-write. Use danger-full-access only in an isolated runner.
• --full-auto is gone. Replace it with --sandbox workspace-write, or --approve-for-me for automatic approval review.
• Machine-readable output. --json emits JSON Lines events (thread.started, turn.completed, item.* and so on). -o result.md writes the final message to a file.
• Structured results. --output-schema schema.json asks for a final response matching a JSON Schema.
• Multi-step pipelines. codex exec resume --last "now fix what you found" continues the previous run.
• Git required. Codex refuses to run outside a git repository unless you pass --skip-git-repo-check.
• Clean environments. --ephemeral skips saving session files; --ignore-user-config skips your config.toml.

For CI, set CODEX_API_KEY only on the step that runs Codex, never as a job-wide variable in workflows that run repository code. On GitHub, OpenAI recommends the openai/codex-action action, which keeps the API key behind a proxy. The codex-exec-ci and codex-github-action skills cover both.

config.toml essentials

User settings live in ~/.codex/config.toml:

model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"            # "live", "indexed" or "disabled"

[sandbox_workspace_write]
network_access = false

[shell_environment_policy]
ignore_default_excludes = false  # filter variables named *KEY*, *SECRET*, *TOKEN*

Set model = "..." only if you want to pin one; /model shows what your account can use.

Precedence, highest first: CLI flags and -c overrides; project .codex/config.toml files (trusted projects only, closest wins); the profile file chosen with --profile; ~/.codex/config.toml; managed and system config (/etc/codex/config.toml); built-in defaults.

Profiles changed recently. Since Codex 0.134.0 a profile is its own file, not a [profiles.name] table:

# ~/.codex/deep-review.config.toml
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"

codex --profile deep-review
codex exec --profile deep-review "review this change for race conditions"

Use /debug-config in a session to see which layers set what. The codex-config-toml and codex-profiles skills set these up with you.

Sandbox and approvals

Two separate controls: the sandbox decides what commands can touch; the approval policy decides when Codex asks. In a git repository Codex recommends the Auto preset, workspace-write with on-request approvals: it can read, edit and run commands in the workspace, and asks before writing elsewhere or using the network. .git, .agents, .codex and .aws inside the workspace stay read-only.

Intent	Flags
Normal local work	--sandbox workspace-write --ask-for-approval on-request
Read and plan only	--sandbox read-only --ask-for-approval on-request
Read-only CI	codex exec (default)
Fewer prompts, same boundary	-c approvals_reviewer=auto_review or --approve-for-me
No boundary at all	--yolo, only in a disposable environment

The older approval_policy = "untrusted" has been retired and can stop Codex from starting; remove it. If you want commands in a particular project to require approval, mark the project instead in ~/.codex/config.toml:

[projects."/path/to/project"]
trust_level = "untrusted"

This also stops Codex from loading that project’s .codex/ configuration. See codex-sandbox-approvals for per-task choices and the skill safety guide for how this applies to skills.

AGENTS.md

Codex reads ~/.codex/AGENTS.md plus one AGENTS.md (or AGENTS.override.md) per directory from the repository root to your working directory, up to 32 KiB combined. Put build and test commands, conventions and boundaries there. /init drafts one. Details in the AGENTS.md guide.

Skills

Skills are folders with a SKILL.md that Codex loads when a task matches, from .agents/skills in the repository and ~/.agents/skills for you. Type $ or run /skills to use one explicitly. Install from this catalog with:

curl -fsSL https://codexskills.dev/install.sh | sh -s -- systematic-debugging implementation-planning

Start with what Codex skills are and the install guide.

MCP

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add docs --url https://developers.openai.com/mcp
codex mcp list

Servers are stored in config.toml and shared with the IDE extension and desktop app. See the Codex MCP guide.

Other commands

Command	Use
codex resume [--last]	Reopen a previous interactive session (sessions are saved in ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl)
codex fork <ID>	Branch an earlier session into a new chat
codex exec resume --last	Continue the last non-interactive run
codex review --uncommitted	Non-interactive review of local changes (also --base, --commit)
codex cloud	Browse or submit Codex cloud tasks from the terminal
codex apply <task-id>	Apply a cloud task’s diff locally
codex doctor	Diagnostic report for a broken install
codex debug prompt-input	Show the exact first-turn context, including AGENTS.md and the skills list
codex debug models	Print the model catalog Codex sees
codex exec --strict-config	Fail on config keys this version does not recognize
codex completion zsh	Shell completions
codex features list	Show feature flags and their state

Tips that save time

1. Say how to verify. “Run pnpm test and show the summary” turns a guess into a checked result. The prompting guide has more.
2. Plan big changes. Use /plan first, edit the plan, then let Codex implement it.
3. Keep context lean. /compact after long runs; point Codex at files with @ instead of asking it to search everything.
4. Use worktrees for parallel work. codex --worktree starts in a managed git worktree so two tasks do not collide.
5. Prefer narrow grants. --add-dir or a network allowlist beats switching to full access.
6. Fix repeated mistakes once. If you correct Codex twice for the same thing, add it to AGENTS.md or write a skill.