Blog

How to use Codex CLI: install, config, models and CI

A practical guide to OpenAI's Codex CLI, from install and sign-in to permissions, config.toml, AGENTS.md, MCP servers, model choice and CI runs.

Alex Mercer

Codex CLI is OpenAI's open-source coding agent for the terminal, which reads your repository, edits files and runs commands inside a sandbox. To use it, install it with OpenAI's installer, npm or Homebrew, run codex in a project folder, sign in with a ChatGPT account or an OpenAI API key, and describe the change you want.

Commands, flags and plan details come from OpenAI's docs and the openai/codex repository as of October 13, 2026. Codex changes often, so trust the linked docs if something has moved.

If you're still choosing an agent, start with the best AI coding tools and agents, with Bug Bench data. For head-to-head comparisons, see Codex vs Claude Code and Cursor vs Codex.

Install Codex CLI

The CLI runs on macOS (Apple Silicon and x86_64), Linux (x86_64 and arm64) and Windows, per the openai/codex README. OpenAI's CLI page gives these install commands:

# macOS or Linux: standalone installer (run it again to update)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm (run it again to update)
npm install -g @openai/codex

# Homebrew
brew install --cask codex
brew upgrade --cask codex   # to update
# macOS or Linux: standalone installer (run it again to update)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm (run it again to update)
npm install -g @openai/codex

# Homebrew
brew install --cask codex
brew upgrade --cask codex   # to update
# macOS or Linux: standalone installer (run it again to update)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm (run it again to update)
npm install -g @openai/codex

# Homebrew
brew install --cask codex
brew upgrade --cask codex   # to update

On Windows, open a new PowerShell window and run:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The README also points to prebuilt binaries on the repo's GitHub Releases page.

On Linux and WSL2, install bubblewrap as well, because Codex uses it to sandbox commands: sudo apt install bubblewrap on Ubuntu or Debian, or sudo dnf install bubblewrap on Fedora. Without it, Codex shows a startup warning and falls back to a bundled helper that needs unprivileged user namespaces. On macOS, sandboxing works out of the box with the built-in Seatbelt framework, and on Windows, Codex uses a native Windows sandbox in PowerShell (sandbox docs).

Sign in with ChatGPT or an API key

Open a project directory and start Codex:

cd

cd

cd

The first run asks you to sign in. There are two ways to do it (authentication docs):

  • Sign in with ChatGPT for subscription access. codex login opens a browser window, and the browser passes your credentials back to the CLI. Usage counts toward your plan's limits, and /status shows what's left during a session.

  • Sign in with an API key for usage-based billing at standard API rates: printenv OPENAI_API_KEY | codex login --with-api-key. The models you can use follow your key, and features that need a ChatGPT workspace, such as Codex cloud, aren't available.

OpenAI's pricing page lists the CLI for ChatGPT Plus, Pro, Business, Edu and Enterprise, and for API keys. Plus and Pro users who hit their limits can buy credits instead of upgrading.

A few more sign-in details:

  • On a remote or headless machine, codex login --device-auth signs in with a device code (beta). Turn on device code login in your ChatGPT security settings first, or ask a workspace admin to.

  • codex login status shows the active method, and codex logout clears stored credentials.

  • Codex caches credentials in ~/.codex/auth.json or your OS credential store. Treat that file like a password.

  • The sign-in method decides which data rules apply. ChatGPT sign-ins follow your workspace's permissions and retention settings; API keys follow your API organization's settings.

Run your first task

OpenAI's getting-started steps use this as a first prompt:

Then ask for one focused change. Commit first: OpenAI recommends Git checkpoints before and after a task so you can revert.

These commands cover most sessions (CLI reference):

Command

What it does

/init

Generates an AGENTS.md scaffold in the current directory

/model

Chooses the model and reasoning effort

/permissions

Sets what Codex can do without asking first

/diff

Shows the Git diff, including files Git isn't tracking yet

/status

Shows session configuration and token usage

/compact

Summarizes the chat to free tokens

/new

Starts a new chat in the same CLI session

/mcp

Lists configured MCP tools

codex resume

Reopens a saved chat from the current repository

codex cloud

Sends work to a configured cloud environment and applies the result locally (ChatGPT sign-in only)

Two launch flags help early on: --image (-i) attaches a screenshot or diagram to the first prompt, and --search turns on live web search for that run.

Set approval and sandbox modes

Two controls decide how much Codex does on its own (agent approvals and security):

  • The sandbox sets what commands can touch: read-only, workspace-write or danger-full-access. It applies to every command Codex spawns, including git, package managers and test runners.

  • The approval policy sets when Codex stops to ask: on-request (before crossing the sandbox boundary) or never.

Network access is off by default. At launch, Codex checks whether the folder is under version control. In a version-controlled folder it recommends Auto (workspace-write with on-request approvals); elsewhere it recommends read-only. Depending on your setup, it may start read-only until you trust the directory. Even when a folder is writable, .git, .codex and .agents inside it stay read-only.

Goal

Flags

Effect

Everyday work in a Git repo (Auto)

None, or --sandbox workspace-write --ask-for-approval on-request

Reads, edits and runs commands in the workspace; asks before editing outside it or using the network

Explore without changes

--sandbox read-only --ask-for-approval on-request

Reads files and runs commands in a read-only sandbox

Read-only script or CI job

--sandbox read-only --ask-for-approval never

Same sandbox, and it never asks

No limits

--dangerously-bypass-approvals-and-sandbox (alias --yolo)

No sandbox and no approvals; OpenAI marks it not recommended

-s and -a are short for --sandbox and --ask-for-approval. In a session, /permissions switches modes and shows the active sandbox and writable roots.

When a task needs one more directory, add it with --add-dir instead of switching to full access. When one command has to run outside the sandbox, a rule can allow, prompt or forbid that command prefix.

Older tutorials may show two things that have changed. Codex no longer supports untrusted as a selectable approval policy, and codex exec --full-auto is now a deprecated compatibility flag that prints a warning; use --sandbox workspace-write instead.

Configure Codex with config.toml

Codex reads settings from ~/.codex/config.toml, and the CLI, IDE extension and ChatGPT desktop app share that file (config basics). A small file that pins a model and the Auto defaults:

# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Settings are layered. From highest to lowest priority:

  1. Command-line flags and -c (--config) overrides, such as codex -c log_dir=./.codex-log

  2. Project files at .codex/config.toml, closest to the working directory first (trusted projects only)

  3. A profile picked with --profile <name> (-p), read from ~/.codex/<name>.config.toml

  4. Your user file, ~/.codex/config.toml

  5. Cloud-managed defaults, then /etc/codex/config.toml on Unix, then built-in defaults

Keep each profile to the values that differ from your defaults, such as a different model for quick jobs. If you mark a project as untrusted, Codex skips its project-scoped .codex/ layers, including project config, hooks and rules. The configuration reference lists every key.

Add project instructions with AGENTS.md

Codex reads AGENTS.md files "before doing any work" (AGENTS.md docs). It builds the instruction chain once per run:

  1. Global: ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md.

  2. Project: one file per directory, from the project root (usually the Git root) down to where you started Codex, checking AGENTS.override.md before AGENTS.md.

  3. Merge: files join root first, so the one closest to your working directory comes last and overrides earlier guidance.

Empty files are skipped, and the combined text stops at 32 KiB by default (project_doc_max_bytes). Run /init to scaffold a starter file. OpenAI's best practices guide says a good AGENTS.md covers the repo layout, how to run the project, build and test commands, engineering conventions, constraints and what done means. For example:




To see what Codex loaded, run codex --ask-for-approval never "Summarize the current instructions." from the repo root. If the repo already keeps instructions under another name, list it in project_doc_fallback_filenames.

Instruction files state your rules, but nothing in them checks that the code follows those rules. How to configure coding agents that follow your team's standards covers that gap. If your team also uses Claude Code, our guide to CLAUDE.md and AGENTS.md covers both files.

Connect MCP servers

MCP (Model Context Protocol) servers give Codex tools and context from outside the repo. OpenAI's MCP docs list examples such as Context7 for current developer docs, Playwright and Chrome DevTools for browser control, Sentry for logs, and GitHub for issues and pull requests. Codex supports local STDIO servers and streamable HTTP servers, with bearer token or OAuth authentication.

Add a server from the command line:

codex mcp add context7 -- npx -y

codex mcp add context7 -- npx -y

codex mcp add context7 -- npx -y

Or define it in config.toml, one table per server:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"

Run codex mcp login <server-name> for servers that use OAuth, and /mcp in a session to see what's connected. Per-server options include enabled_tools and disabled_tools to allow or deny specific tools, and required = true to make startup fail if that server can't start. To keep a server to one repository, define it in the repo's .codex/config.toml, which Codex reads only for trusted projects.

OpenAI's guide suggests MCP when the context lives outside the repo, changes often, or when you want Codex to use a tool or a repeatable integration.

Choose a model

In a session, /model switches the model and reasoning effort. At launch or in scripts, use --model (-m). For a default, set model in config.toml; without one, Codex uses a recommended model (models page).

codex -m gpt-6.1-sol
codex exec -m gpt-6-luna "List the TODO comments in src/ as a Markdown table"
codex -m gpt-6.1-sol
codex exec -m gpt-6-luna "List the TODO comments in src/ as a Markdown table"
codex -m gpt-6.1-sol
codex exec -m gpt-6-luna "List the TODO comments in src/ as a Markdown table"

OpenAI's guidance as of October 13:

  • GPT-6.1 Sol (gpt-6.1-sol) is recommended for complex coding and agentic work, with near-Astra performance at a lower cost than Astra. It's still rolling out: Plus, Pro, Business, Enterprise and Edu are included, Enterprise and Edu admins have to turn it on, and Free and Go are not included at launch.

  • GPT-6 Astra (gpt-6-astra) is OpenAI's most capable model, for the hardest end-to-end work.

  • GPT-6 Luna (gpt-6-luna) is the efficient choice for focused, repeatable tasks.

  • GPT-5.6 Sol, Terra and Luna "remain available during the rollout."

Start with the default reasoning effort and raise it when a task needs more planning. In /model, choose a model, then More reasoning… to see Max or Ultra where the model supports them. Max gives a single task more time to reason, and Ultra splits the work across subagents. OpenAI says most tasks need neither.

With an API key, the models available follow your key. Replace gpt-5.3-codex-spark in old configs and scripts, since it's no longer available in Codex, and gpt-5.4 if you sign in with ChatGPT (changelog). Codex with ChatGPT sign-in also drops GPT-5.5, though the API keeps it. OpenAI's models page names GPT-6 Sol (gpt-6-sol) as its replacement on paid plans and GPT-6 Luna on Free and Go.

What Bug Bench shows inside Codex

OpenAI's guidance is one input. Another is how each model's code holds up in review. Bug Bench, cubic's public benchmark, ranks AI coding models by relative bug rate: counted bugs per AI-attributed line in code reviewed by cubic, divided by the rate across all AI-attributed lines in the window. 1.00 is average, and lower is better. A counted bug is a cubic review finding on AI-written code that a developer upvoted or an AI coding agent addressed.

Codex wrote 18.8% of the AI-written code in that review data in the week of October 5. Shares like this describe code reviewed by cubic, not the whole market. Three models were ranked inside Codex:

Model

Relative bug rate inside Codex

Statistically tied with

GPT-5.6 Sol

0.62

none

GPT-6 Astra

1.13

GPT-6.1 Sol

GPT-6.1 Sol

1.22

GPT-6 Astra

"Statistically tied" means the 95% confidence intervals overlap. GPT-5.6 Sol had 38% fewer counted bugs than the all-model average inside Codex, with no tie, and it ranks first of seven models across all agents at 0.65. OpenAI's recommended GPT-6.1 Sol came in at 1.22, statistically tied with GPT-6 Astra, on two weeks of data, since it first appeared in the week of September 28. Across all agents, GPT-5.6 Sol had 47% fewer counted bugs per line than GPT-6.1 Sol (0.65 vs 1.23).

The data is observational, not causal. Teams choose their models, so a rate reflects the code each model was used for as well as the model. OpenAI documents GPT-5.6 Sol's model ID, gpt-5.6-sol, on its GPT-5.6 Sol page, and its Codex models page says the GPT-5.6 models remain available during the rollout.

Run Codex in scripts and CI

codex exec runs a task without the interactive UI (non-interactive mode). Progress streams to stderr and only the final message goes to stdout, so the output pipes cleanly:

codex exec "summarize the repository structure and list the top 5 risky areas"

npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix"
codex exec "summarize the repository structure and list the top 5 risky areas"

npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix"
codex exec "summarize the repository structure and list the top 5 risky areas"

npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix"

Before you script it:

  • It starts read-only. Add --sandbox workspace-write to allow edits, and keep danger-full-access for isolated runners or containers.

  • It can emit machine-readable output. --json turns stdout into a JSON Lines event stream, -o <path> writes the final message to a file, and --output-schema ./schema.json makes the final answer follow a JSON Schema.

  • It needs a Git repository. --skip-git-repo-check overrides that, for environments you know are safe.

  • It can continue. codex exec resume --last "<next step>" picks up the previous run.

  • It can run clean. --ephemeral skips saving session files, and --ignore-user-config skips your config.toml.

  • Required MCP servers are enforced. If a server marked required = true fails to start, codex exec exits with an error.

Credentials in CI

OpenAI recommends API keys for automation and warns against setting OPENAI_API_KEY or CODEX_API_KEY as a job-level variable in workflows that run repository code, since build scripts, tests, dependency hooks or a compromised action in the same job can read it. Scope the key to the Codex step instead:

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"
CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"
CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

On GitHub Actions, OpenAI points to openai/codex-action rather than a shell step. The action installs Codex, starts a Responses API proxy to reduce API key exposure, and runs Codex with a configurable safety strategy. OpenAI's example workflow for fixing failed CI runs uses two jobs: one with read-only repository access runs Codex and saves the diff as a patch artifact, and a second job, which never gets the API key, applies the patch and opens a pull request. OpenAI also advises against exposing Codex execution in untrusted or public environments.

Good habits with Codex CLI

  1. Keep tasks small. One focused change per chat is easier to check and to revert. OpenAI suggests four parts for a prompt: the goal, the context (relevant files or docs), the constraints, and what done looks like.

  2. Plan before big changes. On complex work, ask for a plan before any code. Read-only mode, set with /permissions, lets Codex explore without editing.

  3. Checkpoint with Git. Commit before and after each task.

  4. Show it how to test. Put build and test commands in AGENTS.md, and ask Codex to add tests where needed and run the checks before it reports back. Not showing the agent how to run builds and tests is on OpenAI's list of common mistakes.

  5. Read every diff. /diff shows all of Codex's changes, including new files Git isn't tracking yet. Read it like a pull request from a new teammate: edge cases, error handling, and anything outside the task.

  6. Keep permissions tight. OpenAI's advice is to start with the defaults and loosen them only for trusted repos. Reach for --add-dir or a rule before full access.

  7. Reset long chats. /compact summarizes the conversation to free tokens, and /new starts over.

Local checks don't replace review. On GitHub, cubic reviews pull requests, finds bugs and learns your team's rules, so changes Codex makes get a second check before they merge. The AI code review guide explains how AI review works, and how successful teams ship AI-generated code to production covers the process around it.

FAQ

Is Codex CLI free?

The CLI is free to install and open source under the Apache-2.0 license, but using it requires a ChatGPT plan that includes it or an OpenAI API key. OpenAI's pricing page lists the CLI for Plus, Pro, Business, Edu and Enterprise, each with its own usage limits, and API key usage bills at standard API rates. The Free and Go plan cards on that page mention Codex only in the desktop app.

Is Codex CLI deprecated?

No. OpenAI's pricing page lists the CLI for Plus, Pro, Business, Edu and Enterprise plans and for API keys, and its open source page calls the openai/codex repository "the primary home for Codex open-source development." What OpenAI has retired or deprecated are older parts, such as the untrusted approval policy, the GPT-5.3-Codex-Spark model and the --full-auto flag.

Can I use Codex CLI with an API key instead of a ChatGPT account?

Yes. Create a key in the OpenAI dashboard and run printenv OPENAI_API_KEY | codex login --with-api-key. Usage then bills at standard API rates instead of your plan's included usage, the models you can pick follow the key, and features that need a ChatGPT workspace, such as Codex cloud, aren't available. OpenAI recommends API keys for CI jobs.

What's the difference between Codex CLI and the Codex app?

Both are Codex, and they share config.toml and MCP servers. The CLI lives in your terminal and is the one you script with codex exec. Codex in the ChatGPT desktop app gives you a visual workspace with a diff panel and a permissions menu under the composer, and it's the surface OpenAI's pricing page lists for the Free and Go plans.

Is Codex better than Claude Code?

Neither wins across the board. Codex suits teams that want OpenAI's models, an OS-level sandbox that's on by default and an open-source CLI, while Claude Code suits teams that want Anthropic's Claude models. Bug Bench doesn't publish a single bug rate per agent, so its data doesn't say which agent writes fewer bugs. Codex vs Claude Code compares them in detail.

Table of contents