Install OpenAI Codex CLI: Complete Setup Guide for macOS, Windows & Linux

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

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: [email protected]

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

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

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

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