Codex CLI Install: Setup Guide

OpenAI’s Codex CLI has become one of the most popular ways to bring AI into the terminal — an open-source coding agent that lives in your repo, reads and edits files, runs shell commands, and commits changes, all from the command line. Whether you are on macOS, Linux, or Windows, getting it installed takes about five minutes.

This Codex CLI install guide walks through every install method, both authentication options, essential configuration, and the troubleshooting fixes for the problems people actually hit.

What Is Codex CLI?

Codex CLI is OpenAI’s terminal-based coding agent — the direct counterpart to tools like Claude Code. It opens an interactive session in any directory, with tool access for shell commands, file I/O, git operations, web fetching, and any MCP (Model Context Protocol) servers you connect.

Key facts worth knowing before you install:

Open source under the Apache 2.0 license; the CLI itself is written in Rust.
Four surfaces, one account. Codex exists as a CLI, an IDE extension (VS Code, Cursor, Windsurf, JetBrains), a cloud agent at chatgpt.com/codex, and desktop/mobile apps. They share models, account, and AGENTS.md configuration, so you can mix them.
Default model is a GPT-5.x Codex variant optimized for coding, with reasoning models available for deeper planning.
Two ways to pay: sign in with your ChatGPT subscription (Plus, Pro, Business, or Enterprise) and usage is included, or authenticate with an API key and pay per token.

If you are still deciding which AI assistant fits your workflow overall, our ChatGPT vs Copilot comparison covers the broader landscape — Codex is OpenAI’s answer on the coding side of that battle.

Prerequisites

Before installing, make sure you have:

Node.js 18 or newer — check with node --version. The npm install method needs it. (The standalone install scripts can bootstrap without a pre-existing Node install.)
A ChatGPT account or an OpenAI API key — you will authenticate on first run.
Git — not strictly required, but Codex works best in a git repo (and you will want version control before letting an agent edit files).

That is genuinely it. No Docker, no Python environment, no cloud account.

Codex CLI Install on macOS and Linux

You have three good options. Pick one.

Option 1: npm (recommended for Node users)

npm install -g @openai/codex

This is the canonical method. If you manage Node versions with nvm, fnm, or volta, install Codex under the Node version you actually use day to day.

Option 2: Homebrew (macOS)

brew install --cask codex

Clean if you already live in the Homebrew ecosystem. Upgrades come through brew upgrade like everything else.

Option 3: Install script (no Node required)

curl -fsSL https://chatgpt.com/codex/install.sh | sh

This fetches the standalone build — useful on fresh servers or minimal Linux boxes where you do not want a full Node toolchain.

Verify the install

codex --version

You should see a version number (releases move fast — 0.154.x was current as of September 2026). If the command is not found, your npm global bin directory is probably not on your PATH; see the troubleshooting section below.

Upgrade later

npm install -g @openai/codex@latest

Or brew upgrade for the Homebrew install. Codex ships frequently, and newer versions meaningfully improve agent behavior — staying within a few releases of latest is worth it.

Install on Windows

Windows has two paths depending on your setup.

Option 1: PowerShell (native Windows)

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

This installs the native Windows build. Run PowerShell as your normal user — no admin rights needed for a user-local install.

Option 2: WSL2 (recommended for developers)

If you already do development in WSL2, just use the Linux instructions inside your WSL distribution:

npm install -g @openai/codex

Codex works beautifully in WSL2, and you avoid the usual Windows path-quoting headaches. This is the setup most Windows-based developers end up happiest with.

Verify on Windows

codex --version

Authenticate: ChatGPT Sign-In vs API Key

On first run, Codex asks how you want to authenticate. This choice matters — pick deliberately.

Method 1: Sign in with ChatGPT (recommended for most)

cd your-project
codex

On first launch you will be prompted to sign in with ChatGPT via your browser. Usage is included in your Plus, Pro, Business, or Enterprise plan. This is the simplest option and the right default unless you have a specific reason otherwise.

Advantages: no API billing to monitor, no keys to rotate, and full access to cloud features like shared threads.

Method 2: API key

Set your key as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

Or persist it in your shell profile:

echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Alternatively, configure it in ~/.codex/config.toml:

preferred_auth_method = "apikey"

API-key auth bills per token and is the right choice for CI/CD pipelines, precise cost control, or if you do not have a ChatGPT subscription. Note that some cloud features (like shared threads) are unavailable with API-key auth.

You can switch methods anytime:

codex --config preferred_auth_method="chatgpt"

A practical pattern many developers use: ChatGPT subscription for daily interactive work, API key as the fallback when subscription quotas run dry.

Your First Codex Session

With installation and auth done, the workflow is:

cd your-project
codex

That is the whole ceremony. Codex opens an interactive session in your project directory. Try:

“Explain the structure of this repo”
“Add input validation to the signup form”
“Write tests for the auth module”
“Find the bug causing the login redirect loop”

The one habit that matters: make a git commit before you let Codex loose on a project. A clean checkpoint means git reset can undo anything. This single habit prevents more disasters than any configuration option.

Codex will propose file edits and shell commands, showing you diffs before applying them (depending on your approval settings). Start in the default approval mode — which asks before running commands — until you trust its judgment in your repo.

Essential Configuration

Codex reads configuration from a five-layer priority system (highest to lowest):

CLI args and --config overrides
Profile config (--profile)
Project config (.codex/config.toml in your repo)
User config (~/.codex/config.toml)
System config (/etc/codex/config.toml)
Built-in defaults

In practice, you will touch two files:

User config (~/.codex/config.toml) — your global defaults: preferred model, auth method, approval policy.

Project config (.codex/config.toml) — per-repo settings you can commit and share with your team.

You can also drop an AGENTS.md file in your repo root with instructions Codex follows in every session (“run tests with npm test, never commit directly to main, …”). This file is shared across all four Codex surfaces, so conventions you write once apply in the CLI, IDE extension, and cloud agent alike.

Useful Commands Cheat Sheet

Command	What it does
`codex`	Start an interactive session in the current directory
`codex --version`	Show installed version
`codex login`	Re-authenticate (browser OAuth)
`codex mcp add <name> --url <url>`	Connect an MCP server
`codex mcp list`	List configured MCP servers
`codex --config key="value"`	Override a config value for one run
`codex --profile <name>`	Run with a named config profile
`npm install -g @openai/codex@latest`	Upgrade to the latest release

MCP servers are worth a special mention: they extend Codex with external tools — databases, browsers, project management APIs — via the Model Context Protocol. codex mcp add plus the server URL is all it takes, and codex mcp list verifies the connection.

Updating and Uninstalling

Update (npm): npm install -g @openai/codex@latest
Update (Homebrew): brew upgrade
Uninstall (npm): npm uninstall -g @openai/codex
Uninstall (Homebrew): brew uninstall --cask codex

Your configuration in ~/.codex/ survives uninstalls, so reinstalling later picks up where you left off. Delete that directory manually if you want a truly clean slate.

Troubleshooting Common Install Problems

“codex: command not found” after npm install

Your npm global bin directory is not on PATH. Find it with npm config get prefix, then add <prefix>/bin to your PATH in ~/.zshrc or ~/.bashrc. This is the single most common install issue and it is always PATH.

Node version errors

Codex needs Node 18+. If your system Node is older, install a modern Node via nvm/fnm — or skip Node entirely and use the curl install script.

Auth loops in the browser

If “Sign in with ChatGPT” opens the browser but never completes, check for aggressive popup blockers or VPN interference, then run codex login again in a fresh terminal. Corporate SSO setups sometimes need the API-key method instead.

Permission errors on install

Never sudo npm install -g. Fix npm’s directory permissions properly (npm’s docs cover the one-time chown), or use a Node version manager, which sidesteps the problem entirely.

Codex is slow or unresponsive

First, check your network — Codex streams from OpenAI’s API. Second, check which model is active; reasoning-heavy models are slower by design. Third, update: performance regressions get fixed quickly and you may be several releases behind.

Codex CLI vs Other AI Coding Tools

The terminal-agent category now has three serious contenders: Codex CLI (OpenAI), Claude Code (Anthropic), and various open-source agents. Since the 2026 model refreshes, the honest answer is that code quality across the top tools is close — the differentiator is ecosystem:

Already paying for ChatGPT Plus/Pro? Codex CLI is included — zero marginal cost.
Living in VS Code with GitHub? GitHub Copilot’s 2026 plans (now usage-based) or its CLI may integrate more smoothly.
Want maximum configurability? Codex’s open-source codebase and MCP support are hard to beat.

For the non-coding side of AI assistants, our ChatGPT vs Copilot comparison remains the best starting point — and if you prefer learning AI tools through guided walkthroughs, our complete Grok AI setup guide follows the same step-by-step philosophy as this article.

Frequently Asked Questions

Is Codex CLI free?

The CLI itself is free and open source. Usage requires either a ChatGPT subscription (Plus/Pro/Business/Enterprise, usage included) or an OpenAI API key (pay per token).

What is the difference between Codex CLI and ChatGPT?

ChatGPT is the conversational interface; Codex CLI is an agentic coding tool that runs in your terminal with file and shell access. They share your account but serve different jobs.

Does Codex CLI work on Windows?

Yes — via the native PowerShell installer or inside WSL2 (recommended for developers).

Which model does Codex CLI use?

A GPT-5.x Codex variant optimized for coding by default, configurable to other models including reasoning models for harder tasks. Check the official Codex documentation for the current default.

Is my code sent to OpenAI?

Yes — Codex sends relevant repo context to OpenAI’s API to do its work, under the same data policies as your chosen auth method (subscription vs API key). Do not point it at repos containing secrets you cannot share.

Can I use Codex CLI in CI/CD?

Yes, with API-key authentication. This is one of the main reasons the API-key auth method exists — subscription auth is designed for interactive use.

Final Thoughts

Installing Codex CLI is the easy part — one npm command, one login, and you have a capable coding agent in your terminal. The real gains come from the habits around it: commit before agent runs, write a good AGENTS.md, configure approval modes deliberately, and pick the auth method that matches how you work. Do that, and the terminal becomes the fastest place you write code.

For the authoritative reference as the tool evolves, keep the official Codex docs bookmarked. And when you want a look at where the hardware running all of this is heading, our roundup of the latest quantum computing breakthroughs is worth your time.

Running Codex Non-Interactively

The interactive session is the headline, but Codex also runs headless — which unlocks scripting:

codex exec "refactor the auth module to use the new session API"

Non-interactive mode is how you wire Codex into scripts, git hooks, and CI pipelines: lint-fix on pre-commit, generate changelogs on release tags, triage failing tests on a schedule. Pair it with API-key auth (subscription auth is designed for humans at keyboards) and treat each invocation as a billed job with a clear, bounded prompt. The narrower the task description, the better the cost-to-value ratio.

Writing a Great AGENTS.md

AGENTS.md is the highest-leverage file in a Codex workflow. It is loaded into every session in that repo, across the CLI, IDE extension, and cloud agent. Good ones are specific and short:


- Package manager: pnpm. Never use npm directly.
- Tests: `pnpm test`. All new features need tests.
- Never commit to main; always create a feature branch.
- API responses use snake_case; the frontend converts to camelCase.
- Before finishing, run `pnpm lint` and `pnpm typecheck`.

What makes this work: every line is a rule Codex would otherwise guess at (and guess wrong). What does not work: pasting your entire employee handbook. Keep it under a page, update it when conventions change, and review what the agent does the first few times — then encode the corrections back into the file. After a month, your AGENTS.md becomes institutional knowledge that onboards every future agent session automatically.

Security Best Practices for Agentic Coding

An agent with shell access deserves the same caution as a junior developer with production credentials:

Never run Codex with secrets in the environment it can read unless the task needs them. It will happily cat your .env into context.
Use approval modes deliberately. Full-auto mode is for sandboxes; keep human approval on for anything touching production, databases, or external APIs.
Review diffs before commit. Codex shows you what it changed — actually read it, especially in auth, billing, and crypto code.
Scope the working directory. Run Codex in the repo it should touch, not in your home directory with access to everything.
Rotate API keys used for automation, and prefer short-lived credentials in CI.

None of this is Codex-specific — it applies to every terminal agent. But Codex’s power (real shell access, real file writes) is exactly why the discipline matters.

When to Skip the CLI: Codex Cloud

Sometimes the terminal is the wrong surface. Codex cloud (at chatgpt.com/codex) runs the same agent in a hosted sandbox: you describe a task in the browser, it works in the background, and it opens a pull request when done. No local install, no terminal, parallel tasks.

Reach for cloud when: the task is long and independent (dependency upgrades, test backfills), you want it running while you do something else, or the machine in front of you is not your dev machine. Reach for the CLI when: you want tight iteration, you need local tools and credentials, or you are exploring unfamiliar code interactively. Most serious users end up with both — CLI for the workday, cloud for the overnight queue.

Frequently Asked Questions (Continued)

Can I use Codex CLI without a ChatGPT subscription?

Yes — authenticate with an OpenAI API key instead and pay per-token API rates. The CLI itself is free and open source either way.

How is Codex CLI different from GitHub Copilot CLI?

Both are terminal coding agents, but they are built around different model families and ecosystems. Codex is OpenAI-native (GPT models, ChatGPT subscription billing); Copilot CLI is GitHub-native (multiple models, GitHub AI Credits billing). If you already pay for one ecosystem’s subscription, its CLI is the path of least resistance.

Does Codex CLI work offline?

No. It calls OpenAI’s API for every substantive action, so it needs a network connection. The install is local; the intelligence is not.

Where are my Codex settings stored?

User-level: ~/.codex/config.toml. Project-level: .codex/config.toml in the repo. Auth state: ~/.codex/auth.json. Back these up if you migrate machines — or better, commit the project-level config to the repo.