Codex CLI Installation Guide: Setup OpenAI's AI Coding Agent in Minutes

Updated 2026-10-15: if you searched for “codex install cli”, install the official @openai/codex package with npm install -g @openai/codex, check codex --version, and run codex inside your project. Complete the sign-in method offered by the installed client; downloading the CLI and paying for model access are separate steps. On macOS and Linux, check that the npm global binary directory is on your shell PATH. On Windows, follow the current official Windows instructions or use WSL when you need a Linux environment. A successful installation does not by itself validate a third-party model endpoint or authorize automatic shell commands.

codex install cli: install, verify, then authenticate#

# Install the official package, then confirm which binary your shell resolves.
npm install -g @openai/codex
codex --version
command -v codex
codex --help

Use the official Codex CLI documentation for the current platform and authentication flow. Treat codex --help from your installed release as authoritative for flags: older tutorials can describe a different client generation. Run the client in a small repository first and inspect the permissions before giving it a broad task.

OpenAI's Codex CLI is a terminal-based AI coding agent that reads your codebase, suggests edits, runs commands, and helps you ship code faster — all from the command line. If you've been looking for a way to bring AI-assisted development directly into your workflow without leaving the terminal, Codex CLI is worth your attention.

This guide walks you through installing Codex CLI on macOS, Linux, and Windows (via WSL), configuring your API key, and getting productive with it immediately.

What Is Codex CLI?#

Codex CLI is an open-source, lightweight coding agent built by OpenAI. Unlike browser-based AI assistants, it runs entirely in your terminal. You describe what you want in natural language, and Codex CLI:

• Reads and understands your project files
• Generates and applies code changes
• Runs shell commands on your behalf
• Handles multi-file edits in a single session

It's designed for developers who prefer keyboard-driven workflows and want AI assistance without context-switching to a browser.

System Requirements#

Before installing, make sure your system meets these requirements:

Step 1: Install Node.js#

Codex CLI requires Node.js v22+. Check your current version:

node --version

If you need to install or upgrade Node.js:

macOS (using Homebrew):

brew install node@22

Ubuntu/Debian:

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

Using nvm (recommended for version management):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

Step 2: Install Codex CLI#

With Node.js ready, install Codex CLI globally:

npm install -g @openai/codex

Verify the installation:

codex --version

You should see the version number printed. If you get a "command not found" error, make sure your npm global bin directory is in your PATH:

export PATH="$(npm config get prefix)/bin:$PATH"

Add this line to your ~/.bashrc or ~/.zshrc to make it permanent.

Step 3: Configure Your API Key#

Codex CLI needs an API key to communicate with the AI model. You have two options:

Option A: OpenAI API Key#

Set your OpenAI API key as an environment variable:

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

Add it to your shell profile for persistence:

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

Option B: Use Crazyrouter as Your API Provider (Recommended)#

For an alternative provider, check the Codex integration page and configure the provider supported by your installed release. An OpenAI-compatible chat endpoint alone does not establish compatibility with the Responses API used by a coding client. Keep API keys in your environment, and do not assume OPENAI_BASE_URL is the complete current Codex configuration.

Step 4: Run Your First Command#

Navigate to a project directory and start Codex CLI:

cd your-project
codex

You'll enter an interactive session. Try a simple prompt:

> Add input validation to the signup form

Codex CLI will analyze your codebase, propose changes, and ask for confirmation before applying them.

Common Commands#

Start interactive work with codex, or inspect codex exec --help for non-interactive tasks. The official documentation describes codex exec, saved sessions, and permission controls. Review the installed client's help before copying flags from an older tutorial.

Step 5: Configure Approval Modes#

Inspect permissions in the current client before it edits files or runs commands. Approval and sandbox controls vary by release and managed policy; a model's response format does not grant filesystem permissions. Use a test checkout for your first task, review the resulting diff, and run your project's existing checks.

Codex CLI vs Alternatives#

How does Codex CLI compare to other AI coding tools?

All three are solid tools. Codex CLI's advantage is its open-source nature and tight integration with the OpenAI ecosystem. If you want to use multiple models, pairing any of these with Crazyrouter gives you flexibility to switch between providers without changing your workflow.

Pricing: Codex CLI API Costs#

As of 2026-10, distinguish installing the open-source client from paying for authenticated model access. Subscription-based sign-in and API-key billing are different arrangements; check the option offered to your account. For a supported alternative route, consult the live GPT-5.3 Codex pricing page and pricing overview. No fixed session cost is implied: repository size, retries, output length, and selected model change usage.

Troubleshooting Common Issues#

"command not found: codex"#

Your npm global bin isn't in PATH. Fix it:

# Find where npm installs global packages
npm config get prefix

# Add to PATH (replace /usr/local with your prefix)
export PATH="/usr/local/bin:$PATH"

"Error: OPENAI_API_KEY is not set"#

Make sure your API key is exported in the current shell:

echo $OPENAI_API_KEY
# Should print your key. If empty:
export OPENAI_API_KEY="sk-your-key"

Node.js Version Too Old#

node --version
# If below v22, upgrade:
nvm install 22 && nvm use 22

Permission Errors on Linux#

# Don't use sudo with npm install -g. Instead, fix npm permissions:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @openai/codex

Slow Responses or Timeouts#

If you're experiencing latency, try using a closer API endpoint. Crazyrouter offers optimized routing that can reduce latency for users in Asia and Europe:

export OPENAI_BASE_URL="https://api.crazyrouter.com/v1"

Advanced Configuration#

Custom Model Selection#

# Use a specific model
codex --model gpt-4.1 "optimize this SQL query"

# Use a cheaper model for simple tasks
codex --model gpt-4.1-nano "add comments to this file"

Project-Level Configuration#

Create a .codex file in your project root:

{
  "model": "gpt-4.1",
  "approval_mode": "suggest",
  "ignore": ["node_modules", "dist", ".env"]
}

Integration with Git#

Codex CLI works well with Git workflows:

# Create a branch, make changes, commit
git checkout -b feature/add-validation
codex "add email validation to the registration endpoint"
git add -A && git commit -m "Add email validation"

FAQ#

codex install cli#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Check the package publisher before installing.

codex cli#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Open a new shell if PATH was recently changed.

codex cli installation#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Keep a record of the installed version when troubleshooting.

codex cli install mac#

Install @openai/codex with npm in your macOS terminal, then check codex --version. If the command is missing, inspect the npm prefix and the PATH used by your active shell before reinstalling. Review permissions before the first repository task.

codex terminal install#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Use the installed help output to confirm available flags.

codex install ubuntu#

In your Linux shell, install the official npm package and verify that command -v codex resolves the expected binary. If npm reports a permission problem, use an appropriate user-owned Node installation rather than changing ownership of system directories blindly. Check the package publisher before installing.

install codex#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Open a new shell if PATH was recently changed.

how to install codex cli#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Keep a record of the installed version when troubleshooting.

install codex terminal#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Review permissions before the first repository task.

codex cli install windows#

Use the current official Windows installation instructions, or install within WSL for a Linux shell. Keep Node, npm, and the Codex binary in the same environment so Windows and Linux paths do not conflict. Use the installed help output to confirm available flags.

codex install bash#

In your Linux shell, install the official npm package and verify that command -v codex resolves the expected binary. If npm reports a permission problem, use an appropriate user-owned Node installation rather than changing ownership of system directories blindly. Check the package publisher before installing.

codex linux install#

In your Linux shell, install the official npm package and verify that command -v codex resolves the expected binary. If npm reports a permission problem, use an appropriate user-owned Node installation rather than changing ownership of system directories blindly. Open a new shell if PATH was recently changed.

linux install codex#

In your Linux shell, install the official npm package and verify that command -v codex resolves the expected binary. If npm reports a permission problem, use an appropriate user-owned Node installation rather than changing ownership of system directories blindly. Keep a record of the installed version when troubleshooting.

codex installation#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Review permissions before the first repository task.

codex cli installer#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Use the installed help output to confirm available flags.

install codex cli macos#

Install @openai/codex with npm in your macOS terminal, then check codex --version. If the command is missing, inspect the npm prefix and the PATH used by your active shell before reinstalling. Check the package publisher before installing.

install codex cli mac#

Install @openai/codex with npm in your macOS terminal, then check codex --version. If the command is missing, inspect the npm prefix and the PATH used by your active shell before reinstalling. Open a new shell if PATH was recently changed.

installing codex#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Keep a record of the installed version when troubleshooting.

openai codex cli installation guide#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Review permissions before the first repository task.

codex cli for linux#

In your Linux shell, install the official npm package and verify that command -v codex resolves the expected binary. If npm reports a permission problem, use an appropriate user-owned Node installation rather than changing ownership of system directories blindly. Use the installed help output to confirm available flags.

codex cli for mac#

Install @openai/codex with npm in your macOS terminal, then check codex --version. If the command is missing, inspect the npm prefix and the PATH used by your active shell before reinstalling. Check the package publisher before installing.

codex cli windows install#

Use the current official Windows installation instructions, or install within WSL for a Linux shell. Keep Node, npm, and the Codex binary in the same environment so Windows and Linux paths do not conflict. Open a new shell if PATH was recently changed.

codex ubuntu install#

In your Linux shell, install the official npm package and verify that command -v codex resolves the expected binary. If npm reports a permission problem, use an appropriate user-owned Node installation rather than changing ownership of system directories blindly. Keep a record of the installed version when troubleshooting.

installing codex cli#

Install the official package with npm install -g @openai/codex, then verify the binary with codex --version. Run codex in a project and follow its authentication prompt; installation alone does not supply model access. Review permissions before the first repository task.

linux codex cli#

In your Linux shell, install the official npm package and verify that command -v codex resolves the expected binary. If npm reports a permission problem, use an appropriate user-owned Node installation rather than changing ownership of system directories blindly. Use the installed help output to confirm available flags.

Is Codex CLI free to use?#

Yes, Codex CLI is free and open source (Apache 2.0 license). You only pay for the API calls to the AI model provider. Using Crazyrouter can reduce these costs by 20-50%.

Can I use Codex CLI with models other than OpenAI?#

Yes. By setting OPENAI_BASE_URL to a compatible API endpoint like Crazyrouter, you can use Claude, Gemini, DeepSeek, and 300+ other models with the same Codex CLI interface.

Is Codex CLI safe to use on production code?#

In the default "suggest" mode, Codex CLI shows you every change before applying it. It won't modify files or run commands without your explicit approval. The --full-auto mode should only be used in sandboxed environments.

How does Codex CLI compare to GitHub Copilot?#

GitHub Copilot is an inline code completion tool integrated into editors. Codex CLI is a terminal-based agent that can make multi-file changes, run commands, and handle complex tasks. They complement each other — use Copilot for line-by-line suggestions and Codex CLI for larger refactoring tasks.

What's the best model to use with Codex CLI?#

GPT-4.1 offers the best balance of capability and cost for most coding tasks. For simple tasks (formatting, comments, renaming), GPT-4.1 nano is much cheaper. For complex architectural decisions, consider using Claude Opus or GPT-4.1 through Crazyrouter.

Summary#

Codex CLI brings AI-powered coding directly to your terminal with a simple npm install. The setup takes under 5 minutes, and you can start shipping code faster immediately.

For the best experience and lowest costs, pair Codex CLI with Crazyrouter — one API key gives you access to 300+ models including GPT-4.1, Claude, Gemini, and more, all at reduced pricing. Sign up at crazyrouter.com to get started.

Related on crazyrouter.com#

• Browse models by vendor
• OpenRouter alternatives