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:
On Windows, open a new PowerShell window and run:
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:
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 loginopens a browser window, and the browser passes your credentials back to the CLI. Usage counts toward your plan's limits, and/statusshows 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-authsigns 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 statusshows the active method, andcodex logoutclears stored credentials.Codex caches credentials in
~/.codex/auth.jsonor 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 |
|---|---|
| Generates an |
| Chooses the model and reasoning effort |
| Sets what Codex can do without asking first |
| Shows the Git diff, including files Git isn't tracking yet |
| Shows session configuration and token usage |
| Summarizes the chat to free tokens |
| Starts a new chat in the same CLI session |
| Lists configured MCP tools |
| Reopens a saved chat from the current repository |
| 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-writeordanger-full-access. It applies to every command Codex spawns, includinggit, package managers and test runners.The approval policy sets when Codex stops to ask:
on-request(before crossing the sandbox boundary) ornever.
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 | Reads, edits and runs commands in the workspace; asks before editing outside it or using the network |
Explore without changes |
| Reads files and runs commands in a read-only sandbox |
Read-only script or CI job |
| Same sandbox, and it never asks |
No limits |
| 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:
Settings are layered. From highest to lowest priority:
Command-line flags and
-c(--config) overrides, such ascodex -c log_dir=./.codex-logProject files at
.codex/config.toml, closest to the working directory first (trusted projects only)A profile picked with
--profile <name>(-p), read from~/.codex/<name>.config.tomlYour user file,
~/.codex/config.tomlCloud-managed defaults, then
/etc/codex/config.tomlon 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:
Global:
~/.codex/AGENTS.override.mdif it exists, otherwise~/.codex/AGENTS.md.Project: one file per directory, from the project root (usually the Git root) down to where you started Codex, checking
AGENTS.override.mdbeforeAGENTS.md.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:
Or define it in config.toml, one table per server:
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).
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:
Before you script it:
It starts read-only. Add
--sandbox workspace-writeto allow edits, and keepdanger-full-accessfor isolated runners or containers.It can emit machine-readable output.
--jsonturns stdout into a JSON Lines event stream,-o <path>writes the final message to a file, and--output-schema ./schema.jsonmakes the final answer follow a JSON Schema.It needs a Git repository.
--skip-git-repo-checkoverrides 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.
--ephemeralskips saving session files, and--ignore-user-configskips yourconfig.toml.Required MCP servers are enforced. If a server marked
required = truefails to start,codex execexits 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:
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
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.
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.Checkpoint with Git. Commit before and after each task.
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.
Read every diff.
/diffshows 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.Keep permissions tight. OpenAI's advice is to start with the defaults and loosen them only for trusted repos. Reach for
--add-diror a rule before full access.Reset long chats.
/compactsummarizes the conversation to free tokens, and/newstarts 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.
