OpenAI Codex CLI: the complete guide

Install and sign in

Four install paths, all producing the same binary. The curl installer is the one OpenAI documents first and the one that self-updates cleanly.

# macOS / Linux, the official installer
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 (it is a cask, not a formula)
brew install --cask codex

codex --version

Sign in

Run codex inside a project and pick Sign in with ChatGPT. That is the path most people want: it bills against your existing subscription rather than a metered API key. As of August 2026 OpenAI lists Codex as included in the Free, Go, Plus, Pro, Business, Edu, and Enterprise ChatGPT plans, with the allowance scaling by tier rather than the feature set changing.

codex login          # opens the ChatGPT sign-in flow
codex logout         # removes stored credentials
codex update         # update in place
codex doctor         # diagnose install, config, auth, and runtime health

Subscription credentials land in auth.json under the config root. Because that path is derived from CODEX_HOME, pointing it somewhere else is how you run a second account without the two clobbering each other.

CODEX_HOME="$HOME/.codex-work" codex login
CODEX_HOME="$HOME/.codex-work" codex

The sandbox model

This is the part that distinguishes Codex and the part worth understanding before you run it on a real repository. Instead of interrupting you for permission on each action, Codex enforces a policy at the operating-system level about what the agent can reach.

codex -s read-only            # research only, cannot modify anything
codex -s workspace-write      # the default, and the sensible one for real work
codex -s danger-full-access   # no boundaries at all

It is enforced by the OS, not by the model

The containment is real rather than an instruction in a system prompt. Codex uses platform-native enforcement: Seatbelt on macOS, bubblewrap on Linux and WSL2 (a bundled helper is available as a fallback), and the native Windows sandbox in PowerShell. A model that decides to write outside the workspace does not get talked out of it, it gets an error from the kernel.

Approval policy is the second dial

The sandbox governs what is possible. The approval policy governs when Codex stops to ask you. Three values, and the list is shorter than it used to be.

codex -a untrusted    # ask before anything not on the trusted list
codex -a on-request   # the default
codex -a never        # never ask (pair this with a tight sandbox)

# Both layers off. Only inside something already isolated.
codex --dangerously-bypass-approvals-and-sandbox

The worktree gotcha, and the flag that fixes it

In workspace-write the writable root is the working directory. Inside a git worktree the real git metadata lives in the main repository’s .git directory, which is outside that root, so git operations that write metadata fail with a permissions error that looks nothing like a sandbox problem.

cd ~/code/myapp-worktrees/feature-auth
codex --add-dir ~/code/myapp

--add-dir takes a directory that should be writable alongside the primary workspace. Point it at the main checkout and commits start working inside worktree sessions. The same thing is available persistently as writable_roots under [sandbox_workspace_write].

config.toml

Anything you find yourself passing as a flag every time belongs in ~/.codex/config.toml. Project-scoped overrides go in a .codex/config.toml inside the repository.

model = "gpt-5.6-sol"
model_reasoning_effort = "high"      # minimal | low | medium | high | xhigh

approval_policy = "on-request"       # untrusted | on-request | never
sandbox_mode = "workspace-write"     # read-only | workspace-write | danger-full-access

[sandbox_workspace_write]
network_access = false
writable_roots = ["/Users/you/code/myapp"]

# Per-project trust
[projects."/Users/you/code/myapp"]
trust_level = "trusted"

# MCP servers
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

Any key can be overridden for a single run with -c. The value is parsed as TOML, so quote strings and use dotted paths for nested keys.

codex -c model_reasoning_effort="high"
codex -c model="gpt-5.6-terra" -c approval_policy="never"
codex -c shell_environment_policy.inherit=all

Reasoning effort is the biggest cost lever

Codex exposes reasoning effort as a first-class setting with five values, and the difference between the ends is large in both quality and price. minimal and low are fine for mechanical edits and dramatically faster. high and xhigh are a genuinely different tool for a hard bug. Most people leave it at the default and never discover either end.

Profiles: switching whole configurations

Once you use Codex for more than one kind of work, a single config stops fitting. Current builds layer a named file on top of your base user config: -p review loads $CODEX_HOME/review.config.toml over config.toml.

model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "read-only"

model_reasoning_effort = "low"
approval_policy = "never"
sandbox_mode = "workspace-write"

codex --profile review "audit this package for race conditions"
codex --profile grind  "convert the remaining callbacks to async/await"

The reasoning-effort difference between those two profiles is the largest lever Codex exposes on both quota and wall-clock time, and switching it per task rather than per account is what makes a subscription last a month.

Interactive, non-interactive, and resuming

cd ~/code/myapp
codex

# Start with a prompt already loaded
codex "add integration tests for the payments module"

# Attach an image (a screenshot of the bug, a design)
codex -i ~/Desktop/error.png "why does this render wrong?"

# Enable live web search for this session
codex --search "check whether the upstream API changed its pagination"

Session management

Sessions are recorded, named, and reachable later. fork is the one people miss: it branches from a previous session so you can try a second approach without losing the first.

codex resume              # picker
codex resume --last       # continue the most recent
codex resume <session-id> # by id or name
codex fork --last         # branch off the most recent session
codex archive <id>        # get it out of the picker without deleting it

Non-interactive, for scripts and CI

codex exec "run the test suite and fix any failures"

# Be explicit about both dials in CI
codex exec -s workspace-write -a never "update the changelog for this release"

# Machine-readable: JSONL events on stdout, final message to a file
codex exec --json -o /tmp/last.txt "summarise the risk in this diff"

# Force the shape of the final answer
codex exec --output-schema ./schema.json "classify each failing test"

codex exec reads from stdin when no prompt argument is given, so it drops into a pipeline without a pseudo-terminal wrapper.

git diff origin/main | codex exec -s read-only "review this diff and list only real defects"

Codex in CI

Two rules make an automated Codex run safe: pin both dials explicitly rather than inheriting a default that may move, and never let it approve its own work.

name: Triage failing tests
on:
  workflow_dispatch:

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Codex
        run: npm install -g @openai/codex
      - name: Diagnose
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec \
            --sandbox workspace-write \
            --ask-for-approval never \
            "Run the test suite. For each failure, explain the root cause in
             docs/triage.md. Do not change application code."
      - uses: actions/upload-artifact@v4
        with: { name: triage, path: docs/triage.md }

The task above is deliberately read-and-report rather than fix-and-push. An agent that opens its own pull request against your main branch on a schedule is a supply-chain question, not a productivity one.

Reviewing a diff without a pipeline

There is also a first-class review subcommand, which is the fastest way to get a second opinion on work another agent just did.

codex review                    # interactive review of the current repo state
codex exec review               # same thing, non-interactively

AGENTS.md: telling Codex about your repo

Codex reads an AGENTS.md file for standing instructions about the project, the same role CLAUDE.md plays for Claude Code. It is the highest-leverage file in the repository for agent quality, and most people never write one. Run /init in a session to have Codex draft the first version.

Files are merged from three levels, most specific winning:

# Project

Go API server. Postgres. Deployed on Fly.

## Commands
- Test a package: `go test ./internal/billing/...`  (NOT the whole suite; it takes 6 min)
- Lint: `golangci-lint run`
- Regenerate mocks after changing an interface: `make mocks`

## Conventions
- Errors wrap with %w and are checked with errors.Is. Never compare strings.
- Any new endpoint needs a table-driven test in the same package.
- internal/pb is generated. Never hand-edit it.

## Do not
- Do not add dependencies without asking.
- Do not touch migrations/ unless the task is explicitly a migration.

MCP servers and tools

Codex speaks the Model Context Protocol, so you can give it tools beyond the filesystem and shell: an issue tracker, a database, internal documentation. Servers are declared in config.toml and start with the session. Codex can also be an MCP server, via codex mcp-server, which is how other agents drive it.

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/dev"]
enabled = true

codex mcp list      # what is configured
codex mcp           # manage servers

Session history and usage

Codex writes a rollout file per session under ~/.codex/sessions/. Those files carry the full transcript plus token counts, which is what any local usage tool reads, and what you should read yourself when a run goes sideways.

ls -lt ~/.codex/sessions/ | head
du -sh ~/.codex/sessions/

# What kinds of events did the newest session produce?
jq -r 'select(.type=="response_item") | .payload.type' \
  "$HOME/.codex/sessions/$(ls -t ~/.codex/sessions | head -1)" | sort | uniq -c

Inside a session, /status prints the current setup: which model, which sandbox, which approval policy, and where you are against your plan’s window.

When it goes wrong

Command and flag reference

Questions people ask

Keep reading