What Is OpenAI Codex CLI? Install, Auth, and First Commands

Checked September 26, 2026 against OpenAI's Codex docs and GitHub

Codex CLI is OpenAI's open source coding agent that runs in your terminal. You describe a task in plain English, and it reads your repository, edits files and runs commands inside a sandbox you control. Install it with npm or Homebrew, sign in with ChatGPT or an API key, then run codex in a project folder.

Codex CLI is OpenAI's free, open-source coding agent for the terminal. It reads your repository, edits files and runs commands when you describe a task in plain English. Install it with npm install -g @openai/codex, or on macOS and Linux with curl -fsSL https://chatgpt.com/codex/install.sh | sh, then run codex in your project folder and sign in with your ChatGPT account. The CLI costs nothing; the model usage behind it comes from your ChatGPT plan or an OpenAI API key. It is one of the two agents most engineering teams now compare when they ask "should we run Claude Code or Codex," alongside GitHub Copilot's agent mode.

Quick answer:

1. Install: npm install -g @openai/codex (or brew install --cask codex)
2. Run codex in your repo, then choose Sign in with ChatGPT
3. Type a task in plain English; Codex reads the repo and proposes changes

The rest of this guide covers what Codex CLI actually is, every install path, how authentication and access work, and what to check before you hand it real work.

What is OpenAI Codex CLI

Codex CLI is OpenAI's open source, terminal-based coding agent, distinct from Codex Web (the cloud-hosted version at chatgpt.com/codex that runs tasks in OpenAI-managed containers) and the Codex IDE extension. The CLI runs locally against your actual filesystem: it reads files, makes edits, and can execute shell commands, inside the sandbox and approval settings you configure.

The project is released under the Apache 2.0 license and lives at github.com/openai/codex, where it had more than 126,000 stars and over 11,400 commits on September 26, 2026. The codebase is written primarily in Rust. The latest release that day was version 0.157.1, up from 0.145.0 in July, which gives a sense of how fast it ships.

If you don't set a model, Codex uses a recommended one. OpenAI's docs currently recommend GPT-6 Sol for complex coding and agentic work and GPT-6 Luna for focused, repeatable tasks, with GPT-6 Astra as the most capable option. You switch with /model inside a session or codex --model gpt-6-sol at launch.

Codex CLI is not a code-completion plugin. It works the way Claude Code and Copilot's agent mode work: you describe a task, it plans and executes across multiple files and terminal commands, and you review the result as a diff.

Install and first run

Four steps get you from nothing to a working session. Commands checked against the OpenAI Codex repo README and the Codex CLI docs on September 26, 2026.

1. Install with npm install -g @openai/codex or, on macOS, brew install --cask codex.
2. Confirm it landed with codex --version.
3. cd into a repository and run codex. On first launch choose Sign in with ChatGPT, or run codex login.
4. Type a task, for example "find why the build fails on Node 20", then review the diff before you keep it.

Run /init in a session to create an AGENTS.md file with instructions for Codex. For permission settings and week-one errors, read how to use Codex.

How to install Codex CLI

OpenAI documents four install paths. Pick one and stick with it, mixing installers is the fastest way to end up with a stale binary shadowing a newer one on your PATH.

To update, rerun the same install script or npm command, or use brew upgrade --cask codex for Homebrew.

A fifth option exists for locked-down environments: download a prebuilt binary directly from the project's GitHub Releases page (separate archives for macOS Apple Silicon, macOS x86_64, Linux x86_64, and Linux arm64), extract it, and rename the binary to codex on your PATH.

Confirm the install landed:

codex --version

How to authenticate Codex CLI

Run codex from your terminal and it walks you through sign-in on first launch, or run codex login directly. You have two options, per OpenAI's own documentation:

• Sign in with ChatGPT. Recommended if you already pay for ChatGPT Plus, Pro, Business, Edu, or Enterprise. The sign-in opens a browser window, and your Codex CLI usage draws from the same plan you already have.
• API key. Pipe a key into the CLI with printenv OPENAI_API_KEY | codex login --with-api-key. Billing runs through your OpenAI Platform account at standard API rates rather than your ChatGPT subscription. OpenAI notes that cloud features such as GitHub code review and Slack are not available in this mode.

Run codex login status to see which method is active. Codex CLI itself is free and open source software; what costs money is the underlying ChatGPT plan or API usage behind it, exactly like Claude Code is free to install while the Anthropic account or API key behind it is what's billed. See the plan prices in the next sections, and check OpenAI's pricing page before you commit a team to a tier, because limits change.

First commands: what running Codex actually looks like

Once you're signed in, the basic loop is:

1. cd into the repository you want Codex to work on
2. Run codex
3. Type what you want done in plain language, "add input validation to the signup form" or "find why the build fails on Node 20"
4. Codex reads the relevant files, then edits and runs commands inside its sandbox. By default the local sandbox limits writes to the active workspace and keeps network access off, and Codex asks for approval before it goes outside those limits
5. Review the diff, keep or revert the changes, iterate

For scripted or CI use, Codex also ships a non-interactive mode (codex exec), so you can hand it a task from a script without the interactive prompt loop. It streams progress to stderr and prints only the final message to stdout, which makes the result easy to pipe into other tools. This is the mode teams reach for when they want Codex to run inside a pipeline rather than a terminal session someone is watching.

Once you're past that first run, see our day-to-day Codex CLI guide for permission settings, giving it project context with AGENTS.md, and the errors people actually hit in week one.

Is Codex CLI free?

The CLI itself, yes: it's open source under Apache 2.0 and costs nothing to install. What it draws on is not free at volume. OpenAI's Codex pricing page lists Plus at $20/month (Codex on the web, in the CLI, in the IDE extension and on iOS), Pro from $100/month with 5x or 20x more Codex usage than Plus, and Business at $20 per user per month billed annually ($25 monthly). Free ($0) and Go ($8/month) list GPT-6 Luna in the desktop app, subject to rollout. Signing in with an API key bills token usage directly through the OpenAI platform. There's no separate "Codex CLI fee" on top of either.

Codex CLI vs the rest of the terminal-agent field

Codex CLI is not the only agent living in a terminal now. If you're choosing between it and the alternatives, the honest short version:

• Claude Code is Anthropic's equivalent, running on Claude models with CLAUDE.md instructions, hooks, MCP and subagents. Codex has its own versions of most of these (AGENTS.md, hooks, MCP, subagents), so the choice usually comes down to models and billing. Our Codex vs Claude Code comparison goes line by line, and how to set up Claude Code covers that path.
• GitHub Copilot's agent mode leans on GitHub-native workflows (PRs, Actions, Issues) more than either Codex or Claude Code. We cover that trade-off in GitHub Copilot vs Claude Code.
• Cursor is IDE-first rather than terminal-first; see Cursor vs Claude Code if your team lives in an editor instead of a terminal.

For a wider list of terminal agents, see best Claude Code CLI tools.

None of these tools is strictly better across every axis. Codex CLI's real advantage is being OpenAI-native: if your team already standardizes on ChatGPT and the OpenAI API, Codex CLI is the path of least friction for billing and account management. If your team is Anthropic-native, that same logic points the other way.

What this means for you

• Install once, pick one method. Mixing npm, brew, and the install script creates PATH conflicts that waste an afternoon.
• Sign in with ChatGPT if you already have a paid plan. It's the simpler billing path; reach for an API key only if you specifically need usage-based billing, for example in CI.
• Review every diff before you keep it. In OpenAI's Auto preset, Codex edits files and runs commands inside your workspace without asking, so commit a Git checkpoint before a task and use /permissions to switch to read-only on a repo you can't afford to have edited wrong.
• Use codex exec for scripted or CI runs, not the interactive session, when nobody is watching the terminal.
• Compare before you standardize a team on it. Weigh Codex CLI against Claude Code and GitHub Copilot's agent mode on your own workflow before committing budget to either.

FAQ

What is OpenAI Codex CLI? Codex CLI is OpenAI's open source, terminal-based coding agent. It reads your repository, proposes and applies code changes, and can run shell commands, distinct from Codex Web (cloud-hosted) and the Codex IDE extension.

Is Codex CLI free? The CLI is free and open source (Apache 2.0). What it uses is not necessarily free: you authenticate either with a ChatGPT plan (Plus at $20/month, Pro from $100/month, Business, Edu, Enterprise) or an OpenAI API key billed separately at API rates.

How do I install Codex CLI? npm install -g @openai/codex, brew install --cask codex on macOS, or the official install script (curl -fsSL https://chatgpt.com/codex/install.sh | sh on macOS/Linux, a PowerShell equivalent on Windows). Prebuilt binaries are also available from the project's GitHub Releases.

What are the main Codex CLI commands? Run codex to start an interactive session in your current repository. Run codex exec for non-interactive, scriptable runs, useful in CI. Run codex login to sign in, codex resume to reopen a recent chat, and codex --version to confirm your installed version.

Does Codex CLI require a ChatGPT subscription? Not strictly. You can sign in with a ChatGPT account (Plus, Pro, Business, Edu, or Enterprise) or authenticate with an OpenAI API key instead, billed through the API. OpenAI notes that cloud features such as GitHub code review and Slack aren't available with an API key.

Is Codex CLI the same as Codex Web? No. Codex Web runs tasks in OpenAI-managed cloud containers you review in a browser. Codex CLI runs locally against your own filesystem and terminal, inside a local sandbox with approval prompts for actions outside it.

How is Codex CLI different from Claude Code? Both are terminal-based coding agents with a similar core loop: describe a task, review a diff, keep or revert. They differ mainly in model provider (OpenAI's GPT-6 family versus Anthropic's Claude), license (Codex CLI is Apache 2.0, Claude Code is proprietary), and billing path.

What language is Codex CLI written in? The public repository is primarily Rust.

Which model does Codex CLI use? If you don't pick one, Codex uses a recommended model. OpenAI currently recommends GPT-6 Sol for complex coding and agentic work and GPT-6 Luna for focused, repeatable tasks, with GPT-6 Astra as its most capable model. GPT-5.5 retires from Codex with ChatGPT sign-in on October 14, 2026. Switch with /model.

What are Codex CLI's approval and sandbox modes? Codex pairs a sandbox mode (read-only, workspace-write, or danger-full-access) with an approval policy such as on-request or never. By default the sandbox limits writes to your workspace and keeps network access off. Use /permissions in a session, or flags like --sandbox read-only, to change it.

Can I use Codex with the free ChatGPT plan? OpenAI's pricing page lists Free ($0) and Go ($8/month) with GPT-6 Luna at Standard speed in the desktop app, subject to rollout. Codex in the CLI is listed from the Plus plan ($20/month) upward. You can also use the CLI with an API key and pay standard API rates.

How do I run Codex CLI for the first time? Install it with npm or Homebrew, open a terminal in your project folder and run codex. Choose Sign in with ChatGPT when prompted, or run codex login yourself. Then type a task in plain English and review the diff Codex proposes.

How do I update Codex CLI? Rerun the installer you used. For npm that is npm install -g @openai/codex, for Homebrew brew upgrade --cask codex, and for the script installers run the same script again. Check the result with codex --version.

Does Codex CLI work on Windows? Yes. OpenAI documents a PowerShell install script for Windows: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex". The npm package also installs on Windows if you already use Node.

How do I give Codex CLI project instructions? Run /init in a Codex session. OpenAI's docs say it creates an AGENTS.md file with instructions for Codex. Edit that file to state your build commands, style rules and boundaries, and commit it with the repo.

Sources: OpenAI Codex CLI on GitHub, Codex CLI docs, Codex authentication, Codex models, Codex pricing, Codex agent approvals and security, Codex quickstart, OpenAI

If you are evaluating Codex CLI for a team rollout rather than a solo trial, see our Codex development agency for how we integrate it into real CI/CD and engineering workflows.