Install Codex CLI: Fix "command not found" & PATH Errors

OpenAI Codex CLI is a terminal-based AI coding assistant that can understand your codebase, execute commands, and help you write code. This guide covers installation on all major platforms.

Prerequisites

Before installing Codex CLI, ensure you have:

• Node.js 18 or later: Check with node --version
• npm 8 or later: Check with npm --version
• OpenAI account: Sign up at platform.openai.com
• API credits: New accounts get $5 free; or use ChatGPT Plus/Pro

Installation

macOS

# Install via npm
npm install -g @openai/codex

# Verify installation
codex --version

# Authenticate
codex auth

On a system-installed Node, that global install often stops with EACCES: permission denied because npm's global directory is owned by root; resist the urge to re-run it with sudo, and fix the npm EACCES permission denied error when installing Codex by moving npm's prefix into your home directory instead.

Linux

# Install Node.js if needed (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Codex CLI
npm install -g @openai/codex

# Verify installation
codex --version

# Authenticate
codex auth

Windows

Option 1: PowerShell

# Install via npm
npm install -g @openai/codex

# Verify installation
codex --version

# Authenticate
codex auth

Option 2: WSL (Recommended)

# In WSL terminal
npm install -g @openai/codex
codex --version
codex auth

Authentication

Codex CLI requires an OpenAI API key. You have two options:

Option 1: Interactive Login (Recommended)

codex auth

This opens your browser for secure authentication. Your credentials are stored in the system keychain.

Option 2: Environment Variable

# Get your API key from platform.openai.com/api-keys
export OPENAI_API_KEY="sk-..."

# Add to shell profile for persistence
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc

Verify Authentication

codex auth status
# Should show: Authenticated as: your-email@example.com

Quick Start

After installation, test Codex CLI:

# Navigate to a project
cd ~/projects/myapp

# Start an interactive session
codex

# Or run a single command
codex "explain what this codebase does"

Example Commands

# Get help with code
codex "how do I add user authentication to this app?"

# Review code
codex review

# Generate code
codex "create a function to validate email addresses"

# Fix bugs
codex "fix the TypeError in src/utils.js"

Troubleshooting Installation

If the installer itself fails before you get this far — reporting Could not find Codex package or platform npm release assets for Codex — that is a release-metadata problem rather than a PATH problem; see Could not find Codex package or platform npm release assets.

Error: "codex: command not found"

Your PATH doesn't include npm's global bin directory.

Fix for macOS/Linux:

# Find npm's bin directory
npm bin -g

# Add to PATH (zsh)
echo 'export PATH=$PATH:$(npm bin -g)' >> ~/.zshrc
source ~/.zshrc

# Or for bash
echo 'export PATH=$PATH:$(npm bin -g)' >> ~/.bashrc
source ~/.bashrc

Fix for Windows:

1. Run npm bin -g to find the path
2. Add it to System Environment Variables > Path

If the directory is already on your PATH and the shell still cannot find the executable, the install itself may have completed without placing a binary where you expect it; work through unable to locate the Codex CLI binary to find where npm actually put it.

Error: "npm: command not found"

Install Node.js first:

macOS:

brew install node

Linux:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows: Download from nodejs.org or use:

winget install OpenJS.NodeJS.LTS

PowerShell words this differently — npm is not recognized as the name of a cmdlet — and the message frequently persists after Node is installed, because the shell you are typing into is still running with the PATH it inherited at launch.

Error: "EACCES: permission denied"

Don't use sudo with npm. Fix npm permissions:

# Create npm global directory
mkdir ~/.npm-global

# Configure npm to use it
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Now install
npm install -g @openai/codex

Error: "Invalid API key"

1. Check your key at platform.openai.com/api-keys
2. Ensure it starts with sk-
3. Verify you have API credits available
4. Re-authenticate: codex auth

Error: "Rate limit exceeded"

You've hit your API rate limits:

1. Wait a few seconds and retry
2. Check your usage at platform.openai.com/usage
3. Upgrade your plan if needed

Configuration

Config File Location

Codex CLI stores configuration in:

• macOS/Linux: ~/.codex/
• Windows: %USERPROFILE%\.codex\

Settings File

Create ~/.codex/config.json:

{
  "model": "gpt-4",
  "maxTokens": 4096,
  "temperature": 0.7,
  "autoApprove": false
}

Environment Variables

Updating Codex CLI

Check for updates regularly:

# Check current version
codex --version

# Update to latest
npm update -g @openai/codex

# Or reinstall
npm install -g @openai/codex@latest

Uninstalling

To remove Codex CLI:

# Remove the package
npm uninstall -g @openai/codex

# Optional: Remove config files
rm -rf ~/.codex

# Optional: Remove credentials
codex auth logout

Platform-Specific Notes

macOS

• Works on both Intel and Apple Silicon
• Credentials stored in Keychain
• No additional dependencies needed

Windows

• WSL provides the best experience
• Native Windows works but may have path issues
• Credentials stored in Windows Credential Manager

Linux

• Works on all major distributions
• May need to install libsecret for keychain storage:

  # Ubuntu/Debian
  sudo apt-get install libsecret-1-0
  
  # Fedora
  sudo dnf install libsecret
  

  Copy

Next Steps

After installation:

• Use Codex for Code Review - Built-in review command
• Resume Sessions - Continue previous conversations
• Use Image Input - Convert designs to code
• Configure Sandbox Modes - Control file access
• See where Codex CLI stores its configuration files

Compare other AI coding CLIs

• Install Claude Code CLI, Anthropic's agentic terminal assistant
• Install Google Gemini CLI for its 1M-token context window
• Install GitHub Copilot CLI if you already pay for GitHub Copilot
• Compare AI coding CLI pricing across tools and read Claude Code pricing explained