Codex CLI turns your terminal into an AI coding partner. OpenAI built this open-source agent to read your codebase, run commands, and apply patches while you stay in control. You already live in the terminal, so why switch context for every AI-assisted task?
This guide walks you through every installation path — the standalone script, npm, Homebrew, and winget — plus verification, sign-in, and the config options that actually matter. One recurring theme shows up across recent setup guides: the most common Codex CLI install failure isn’t a missing dependency or a platform issue. It’s running the wrong package name in npm. Keep that in mind as you work through the steps below.
What Is Codex CLI, And Who Is It For?
Codex CLI is OpenAI’s terminal-based coding agent. It runs locally on your machine, reads your project files, and executes changes under your approval. Developers who want ChatGPT-level reasoning without leaving the command line reach for it first.
You get three ways onto your system: a standalone installer script, a package manager, or a prebuilt binary from GitHub releases. Each path lands you at the same destination — a working codex command — so pick whichever fits your existing toolchain.
Which Installation Method Should You Choose?
Your operating system and your existing tools decide the best path. A Node.js developer already has npm ready to go. A macOS user with Homebrew installed skips a step. A user who wants zero dependencies grabs the standalone script instead.
Here’s a quick breakdown:
| Method | Best For | Requires |
| Standalone script | Minimal setup, no Node.js needed | curl or PowerShell |
| npm | Cross-platform, Node.js users | Node.js 22+ |
| Homebrew | macOS and Linux users already on brew | Homebrew installed |
| winget | Native Windows installs | Windows 10/11 |
| GitHub binary | Air-gapped or custom environments | Manual PATH setup |
How Do You Install Codex CLI With The Standalone Script?
The standalone installer downloads a prebuilt binary directly, so you skip Node.js and package-manager overhead entirely. Run one of these commands depending on your platform.
macOS and Linux:
bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Windows (PowerShell):
powershell
powershell -ExecutionPolicy ByPass -c “irm https://chatgpt.com/codex/install.ps1 | iex”
OpenAI publishes both commands directly on the official npm package page, so they stay current with each release. Open a fresh terminal window afterward, then confirm the binary landed on your PATH.
How Do You Install Codex CLI With npm?
npm gives you the most predictable cross-platform path, and it works identically on macOS, Linux, and native Windows. First, confirm your Node.js version, since Codex CLI needs a recent release.
bash
npm install -g @openai/codex
Node.js 22 or newer is the canonical requirement, and the package publishes under the @openai/codex scope. Double-check your package name before you hit enter. An unscoped codex package exists on npm too, and it has nothing to do with OpenAI’s agent — that unrelated package dates back to 2012, installs silently, and does nothing useful. Typing npm i -g codex instead of npm i -g @openai/codex wastes real setup time, so copy the scoped command exactly.
Ran into a permission error? Avoid reaching for sudo. A system-installed Node often triggers an EACCES permission-denied error, because npm’s global directory belongs to root. Point npm at a directory in your home folder instead:
bash
mkdir ~/.npm-global
npm config set prefix ‘~/.npm-global’
echo ‘export PATH=~/.npm-global/bin:$PATH’ >> ~/.zshrc
source ~/.zshrc
npm install -g @openai/codex
How Do You Install Codex CLI On macOS With Homebrew?
Homebrew users get a one-line install, and it fits neatly into an existing brew-managed workflow.
bash
brew install –cask codex
Homebrew handles updates through its standard mechanism afterward. A later upgrade runs through brew upgrade –cask codex, so you never touch a manual reinstall. Watch for one quirk though: some brew formulas install the desktop app rather than the CLI binary. Switch to the npm path instead if that happens, since it targets the CLI specifically. Once installed, confirm /opt/homebrew/bin sits on your PATH for Apple Silicon, or /usr/local/bin for Intel Macs.
How Do You Install Codex CLI On Windows Natively?
Windows gives you three real options: winget, npm through PowerShell, or the standalone script above. Which one should you pick?
Winget:
powershell
winget install -e –id OpenAI.Codex
npm (the recommended native path):
powershell
npm install -g @openai/codex
codex –version
The recommended native Windows path runs through PowerShell with npm, using Node.js 22 installed via nvm-windows or a direct download. Native Windows support still carries some rough edges worth knowing about. Codex CLI on native Windows uses an AppContainer-based sandbox that restricts filesystem writes and limits network access by default, and OpenAI still labels Windows sandbox support as experimental. Users on WSL2 generally report smoother sandboxing behavior, so consider that route if you hit persistent sandbox errors.
How Do You Verify Your Codex CLI Installation?
Confirm the install landed correctly before you start a session. Run this in any terminal:
bash
codex –version
A version string confirms success. No output, or a “command not found” error, usually points to a PATH issue rather than a failed install. Close your terminal and reopen a fresh window first — PowerShell in particular often keeps running with the PATH it inherited at launch, so a simple restart resolves most of these.
How Do You Sign In And Authenticate Codex CLI?
Navigate to your project folder, then start the agent for the first time.
bash
codex
You get two authentication paths here. Sign in through your ChatGPT account via the browser flow for subscription-based billing, or authenticate with a developer API key when you’d rather bill through the OpenAI developer dashboard directly:
bash
codex login –with-api-key
Each path unlocks the same functionality, so pick whichever billing model matches your situation. A team account usually favors the API-key route for centralized cost tracking, while an individual developer often finds the ChatGPT subscription simpler.
How Do You Configure Approval Policy And Sandbox Mode?
Codex CLI reads configuration from ~/.codex/config.toml for your personal defaults, and you can layer project-specific overrides through a .codex/config.toml file inside any repo. Codex loads those project-level layers only after you trust the project, which keeps untrusted repos from silently changing your settings.
Two settings shape how much autonomy the agent gets:
toml
approval_policy = “on-request” # untrusted | on-failure | on-request | never
sandbox_mode = “workspace-write” # read-only | workspace-write | danger-full-access
on-request paired with workspace-write covers most day-to-day development. Codex edits files inside your project freely, then pauses before it touches anything outside that boundary or reaches the network. Prefer a fully automated flow inside a disposable container? Run this instead:
bash
codex –dangerously-bypass-approvals-and-sandbox
Save that flag for isolated environments only. A shared or production machine should never skip the sandbox.
What Should You Do If Codex CLI Won’t Run After Install?
A handful of errors account for most post-install failures. Here’s how to work through them.
“npm not recognized” on Windows. Reopen PowerShell in a fresh window. The shell you originally typed into often still carries the PATH state from before Node.js finished installing.
EACCES permission denied during npm install. Reconfigure npm’s prefix to a home-folder directory rather than running the install with sudo, using the steps in the npm section above.
Windows sandbox process-creation failures. Native Windows sandboxing remains experimental, and some users hit CreateProcessWithLogonW errors after an update. Setting experimental_windows_sandbox = false in config.toml and restarting Codex resolves this for most reported cases.
Codex not found after a Homebrew install. Confirm your Homebrew bin directory sits on PATH, or reinstall through npm if the cask pulled the desktop app instead of the CLI.
How Do You Update Or Uninstall Codex CLI?
Updating depends on your original install method. An npm install updates with npm install -g @openai/codex@latest, while Homebrew and winget installs update through their own package managers — brew upgrade –cask codex or winget upgrade OpenAI.Codex.
To remove Codex CLI entirely:
- npm: npm uninstall -g @openai/codex
- Homebrew: brew uninstall –cask codex
- Standalone script: delete the binary from its install directory, then clean up the ~/.codex configuration folder
Frequently Asked Questions
Does Codex CLI need Node.js?
Only for the npm installation path. The standalone script and the prebuilt GitHub binaries run without any Node.js dependency.
Can you run Codex CLI inside WSL2?
Yes, and many Windows developers prefer it. WSL2 sandboxing behaves more predictably than the native Windows AppContainer sandbox, which OpenAI still treats as experimental.
What’s the difference between Codex CLI and Codex Web?
Codex CLI runs locally on your machine and works directly with your local files. Codex Web is OpenAI’s cloud-based agent, accessible through chatgpt.com/codex, and it operates on a remote environment instead.
Which authentication method should you choose?
A ChatGPT subscription covers most individual developers well. Switch to an API key if you need usage-based billing through the OpenAI developer dashboard.
Conclusion
Installing Codex CLI is a valuable step for developers who want to streamline coding tasks, automate workflows, and improve productivity through AI-powered assistance. With its ability to support code generation, debugging, and software development directly from the command line, Codex CLI can make development more efficient and accessible. By learning how to install, configure, and use it effectively, developers can take advantage of modern AI tools to build better software and simplify everyday programming tasks.
USA Parameter — Empowering Businesses with Smarter Digital Solutions, SEO, and Content Strategies.