Codex CLI: The Practical Guide to OpenAI's Terminal Agent (2026)

Codex CLI is OpenAI's open-source coding agent that runs in your terminal: it reads, edits, and executes code in a selected directory, installs with one command via curl, npm, or Homebrew, and authenticates with either a ChatGPT plan or an API key. This guide is the hands-on reference for the CLI tool itself: install, config.toml, models, key commands, and MCP setup. For how the CLI fits alongside the Codex app, IDE extension, and cloud agent, see our broader OpenAI Codex ecosystem guide.

What Is Codex CLI?

Codex CLI is the terminal form of OpenAI's Codex agent: a Rust binary that opens an interactive session in your repository, plans changes, edits files, and runs commands under configurable approval and sandbox rules. It is open source under the Apache-2.0 license, ships for macOS, Windows, and Linux (including WSL2), and is developed in the open at github.com/openai/codex, which stands at 95,866 stars as of July 2026.

"Codex" is now a family name, so be precise about which surface you mean:

All surfaces share your account limits and, notably, the CLI and IDE extension share the same configuration file. The rest of this post stays on the CLI; the ecosystem guide covers when to reach for each surface and how approvals work across them.

How to Install Codex CLI

Codex CLI installs through OpenAI's install script, npm, Homebrew, or direct binary download from GitHub releases. The script route is what the official docs recommend:

# 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
npm install -g @openai/codex

# Homebrew
brew install --cask codex

Then run codex in a project directory. First launch opens an authentication flow with two options: Sign in with ChatGPT, which uses your Plus, Pro, Business, Edu, or Enterprise plan allowance, or an API key for per-token billing. ChatGPT sign-in is the right default for individuals because you pay nothing beyond the subscription you already have.

Prebuilt binaries for Apple Silicon, Intel macOS, and x86_64/arm64 Linux are attached to every GitHub release if you need to pin versions or install without a package manager.

config.toml Essentials

Codex CLI reads its configuration from ~/.codex/config.toml, and a .codex/config.toml inside a repository overrides it per project. A practical starter config covers five keys:

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "on-request"   # untrusted | on-request | never
sandbox_mode = "workspace-write"
web_search = "cached"            # cached | live | disabled

[features]
web_search = true

The two settings that matter most for safety are approval_policy, which controls when Codex pauses to ask before acting (untrusted is strictest, never is full autonomy), and sandbox_mode, where workspace-write confines edits to the current workspace. model_reasoning_effort trades speed for depth, and the [features] table gates optional capabilities like shell snapshots and memories.

When settings conflict, precedence runs from CLI flags and --config overrides, down through project config, profile files, user config, and system config at /etc/codex/config.toml, to built-in defaults. That ordering makes it safe to keep a conservative user config and loosen it per project.

AGENTS.md: project instructions

Alongside config.toml, Codex reads an AGENTS.md file from your repository root for project-specific instructions: build commands, test conventions, code style, and anything else the agent should know before touching files. It plays the same role CLAUDE.md plays for Claude Code, and because AGENTS.md is an open convention, the same file also serves other agents that have adopted it. Keep it short and operational; a ten-line AGENTS.md that says how to run tests beats a page of prose the model has to skim every session.

Models and Pricing

Codex CLI defaults to gpt-5.5, OpenAI's current frontier model for complex coding and agentic work, and as of July 2026 the recommended lineup is four models deep. Switch with codex -m <model> at launch or the /model command mid-session; gpt-5.2 and gpt-5.3-codex are deprecated for ChatGPT sign-in.

Plan-wise, Codex CLI works across the ChatGPT lineup: the Free tier covers quick coding tasks, Go is $8/month, Plus at $20/month buys roughly 15 to 80 gpt-5.5 messages per 5-hour window, and Pro starts at $100/month with 5x or 20x Plus limits. API-key users pay standard per-token rates instead. Full cross-vendor pricing context, including how these numbers stack against Claude's plans, is in our Codex vs Claude Code comparison, and if you want to route Codex to cheaper or local models, see the best free models for Codex.

Key Commands and Flags

Day-to-day Codex CLI use revolves around one entry command, a handful of flags, and slash commands inside the session. The high-leverage set:

Beyond text, the CLI accepts screenshots and design specs as visual input, runs an agent-driven code review before commits, performs web searches when enabled, and can hand tasks to Codex Cloud without leaving the terminal. The exec subcommand is the piece most people underuse: it turns Codex into a scriptable build step, for example running a lint-and-fix pass in CI.

Approvals deserve one practical note. In interactive sessions, Codex pauses for confirmation based on your approval_policy: with untrusted, it asks before nearly everything; with on-request, it asks when it wants to step outside the sandbox; with never, it proceeds autonomously within whatever sandbox_mode allows. Pairing never with workspace-write is the common "fast but contained" setup for repos you trust, while untrusted is the right mode for cloned code you have not read yet.

MCP Support

Codex CLI supports the Model Context Protocol, so it can use the same third-party tool servers as Claude Code and other agents. Registration is one command, or a TOML block if you manage config by hand, and the CLI and IDE extension share this configuration:

# CLI route
codex mcp add context7 -- npx -y @upstash/context7-mcp

# or in ~/.codex/config.toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

HTTP servers are configured with a url plus bearer_token_env_var instead of a command. Whether MCP actually earns its context-window cost in Codex is a real question; our Codex CLI MCP guide covers when servers help, when they slow the agent down, and which ones are worth installing, and our best MCP servers ranking covers the top picks across categories.

Codex CLI vs Claude Code

Codex CLI and Claude Code are the two dominant terminal coding agents in 2026, and the practical difference is models and ecosystem depth: Codex runs OpenAI's GPT-5.5 family with a free tier and an $8 entry plan, while Claude Code runs Claude Opus 4.8 and Sonnet 5 with a deeper customization stack (skills, hooks, and plugins on top of MCP). Codex uses AGENTS.md for project instructions where Claude Code uses CLAUDE.md, and both support MCP.

The short version of our advice: Codex CLI wins on price flexibility and cloud handoff, Claude Code wins on extensibility and long-horizon agent work. The full breakdown, including benchmark caveats and per-plan message limits, is in Codex vs Claude Code.

Limitations and Tradeoffs

Codex CLI's rough edges are worth knowing before you commit a workflow to it. Plan limits are opaque in practice: the 15 to 80 messages per window range on Plus is wide because task complexity changes token burn, so heavy agent sessions can hit limits mid-task. The model menu is OpenAI-only when signed in with ChatGPT; there is no first-party path to run Claude or Gemini through it. Approval and sandbox settings default sensibly, but approval_policy = "never" combined with broad filesystem access hands real power to the agent, so loosen per project rather than globally. And the tool evolves fast enough (0.14x releases shipping weekly as of mid-2026) that pinned versions in CI can drift behind documented behavior.

Related Guides

• OpenAI Codex Guide: App, IDE, MCP, and When to Use It
• Codex CLI MCP: When MCP Actually Improves Codex Workflows
• Codex vs Claude Code: The 2026 Comparison
• Best Free Models for OpenAI Codex