Codex CLI Installation Guide

Prerequisites and System Requirements

Codex CLI runs anywhere your toolchain lives — the surface area is deliberately small.

The Codex CLI is engineered to be lightweight and non-intrusive. It does not require a specific editor, browser, or desktop environment. What it does need is a supported operating system, one of three package managers, and an internet connection for the initial authentication handshake. After authentication, most operations work offline — code generation and review requests queue locally and sync when connectivity resumes. The binary footprint sits around 18 MB on macOS, 14 MB on Linux, and 22 MB on Windows. Disk consumption after installation, including shell completions and man pages, stays under 30 MB across all platforms.

For macOS users, the minimum requirement is macOS 12 Monterey or later. Both Intel and Apple Silicon architectures are supported natively — the Homebrew formula selects the correct binary automatically. Linux support covers any distribution running kernel 4.15 or newer, with explicit testing on Ubuntu 20.04+, Debian 11+, Fedora 37+, and Arch. On Windows, Windows 10 build 19041 or Windows 11 is required; the installer handles both PowerShell 5.1 and PowerShell 7.x environments. The CLI ships as a standalone executable — it does not touch your system PATH in unexpected ways and uninstalls cleanly through the same package manager that installed it.

Installation Methods by Platform

Three package managers, one CLI. Choose the path that fits your existing development environment.

Each installation method delivers an identical CLI binary. The only difference is how your system resolves the executable path. The Homebrew formula places the binary in /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel). npm global installs land in your Node.js prefix, typically /usr/local/lib/node_modules. pip places the entry point in your Python scripts directory. All three paths are added to your shell PATH automatically by their respective package managers, so codex is available immediately after a fresh terminal session.

macOS Installation Walkthrough

Homebrew users get native architecture detection and automatic updates. Everyone else gets npm or pip.

Open Terminal and run brew tap codex/tools to add the Codex formula repository. Then execute brew install codex-cli. Homebrew resolves the correct binary for your architecture, places it in the cellar, and symlinks it into your PATH. The entire process takes roughly forty seconds on a typical broadband connection. Once installed, run codex --version to confirm the binary is reachable. The output should display the version number, build hash, and the detected platform triple — something like codex 2.4.1 (a3f7b92) darwin-arm64. If you prefer npm, ensure Node.js 18 or later is installed and run npm install -g @codex/cli. The postinstall script checks for shell completion frameworks and offers to wire them up. For pip users, create a virtual environment first — python3 -m venv ~/.codex-venv && source ~/.codex-venv/bin/activate — then install with pip install codex-cli.

Linux Installation Details

Whether you are on Ubuntu, Fedora, Arch, or Debian, the CLI installs in one command and respects your distribution's conventions.

npm is the recommended path on Linux because it avoids distribution-specific packaging delays. Run npm install -g @codex/cli and the CLI is available immediately. Snap users can run snap install codex for automatic updates and sandboxed execution — note that the Snap confinement model restricts filesystem access to $HOME and mounted media by default. Grant broader access with snap connect codex:home and snap connect codex:removable-media if your projects live on external drives. For pip, the standard pip install codex-cli works across all distributions. Arch users can also install from the AUR: yay -S codex-cli. After any installation method, run codex doctor to verify that all subsystems — networking, filesystem access, authentication module, and shell integration — are functioning correctly. The doctor command prints a pass/fail checklist with remediation steps for any issues it finds.

Windows Setup and PowerShell Integration

Windows gets first-class treatment — the CLI integrates with PowerShell, Command Prompt, and Windows Terminal equally well.

Install Node.js 18 or later from the official Windows installer, then open PowerShell as Administrator and run npm install -g @codex/cli. The installer adds codex.exe to your global npm prefix and registers shell completion for PowerShell 5.1 and 7.x. If you encounter execution policy restrictions, run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser before installing. Winget users can run winget install Codex.CLI from any terminal — the Microsoft Package Manager handles the installation silently and adds the executable to your user PATH. Verify the installation by opening a new PowerShell window and typing codex --help. The help output lists all available commands with their descriptions. For Windows Subsystem for Linux users, install the Linux variant inside your WSL distribution using npm or pip — the WSL binary and the Windows binary can coexist without conflict, each reading from their respective filesystems.

First-Run Configuration

Five minutes after install, you should have a fully configured CLI that knows your projects, your preferences, and your API credentials.

Run codex setup after installation. The setup wizard asks four questions: your API key (from the Codex dashboard), your preferred language for generated code, your default project directory, and whether to enable telemetry. The API key is stored encrypted in the system keychain on macOS, the Secret Service API on Linux, and the Windows Credential Manager — it is never written to disk in plaintext. After answering the prompts, the wizard scans your default project directory for Git repositories and pre-indexes them. This scan runs once and takes about fifteen seconds per hundred thousand lines of code. Subsequent sessions load the cached index instantly. Telemetry is opt-in and collects only command names and error codes — never file paths, source code, or environment variables. You can change every setting later through codex config or by editing ~/.config/codex/config.toml.

Shell Completion Setup

Tab completion saves keystrokes and prevents typos. The CLI sets it up automatically for bash, zsh, fish, and PowerShell.

The postinstall script detects your active shell and appends the appropriate completion snippet. For bash, it adds a line to ~/.bashrc or ~/.bash_profile. For zsh, it creates a file in your fpath and appends a compinit line to ~/.zshrc. Fish users get a completion file in ~/.config/fish/completions/. PowerShell users receive a registered argument completer. If the automatic setup fails — for example, if you use an uncommon shell or a non-standard config path — run codex completion install --shell bash (substituting your shell) to force the installation. Verify completion is active by typing codex gen and pressing Tab — you should see subcommands and flags appear. The completion engine understands context, so typing codex review -- followed by Tab suggests only the flags relevant to the review command.

Authenticating With Your Codex Account

The CLI authenticates once and stays authenticated. No repeated logins, no browser dance every morning.

Grab your API key from the Codex dashboard at codex.gr.com — it is under Settings > API Keys. Copy the key and run codex auth --key YOUR_API_KEY. The CLI hashes the key, stores it in the platform keychain, and validates it against the Codex API. A successful authentication prints your account email and plan tier. If you are on a team plan, the CLI also displays the team name. For CI/CD environments, set the CODEX_TOKEN environment variable instead — the CLI reads it on startup and skips keychain storage entirely. Rotate keys from the dashboard at any time; the old key stops working immediately and the CLI prompts for the new one on the next command. You can also authenticate via OAuth device flow: run codex auth --device, visit the URL printed in the terminal, and enter the eight-character code. This method is useful for machines where you cannot copy-paste easily, like remote servers accessed over SSH.

Project Initialization and Context Indexing

Navigate to any project directory and run codex init. Thirty seconds later, the CLI understands your codebase.

The codex init command scans the current directory for a Git repository, reads .gitignore to exclude generated files, and builds a semantic index of your code. The indexer parses import graphs, function signatures, type definitions, and docstrings. It respects your project's language and framework — a React project gets component tree analysis, a Go project gets package dependency resolution, a Python project gets virtual environment detection. The index is stored in .codex/index.db, which you should add to .gitignore (the CLI adds it automatically). The index is incremental — subsequent runs of codex init or codex index --update only re-parse files that changed since the last index. On large monorepos, the initial index can take a minute or two; the CLI shows a progress bar with file count and estimated time remaining. Once indexed, every codex generate and codex review command uses the index to provide contextually relevant output.

Running Your First Codex CLI Command

The moment of truth: open a terminal, type a natural language description, and watch Codex produce working code.

With your project indexed and authentication set, try codex generate "a function that validates email addresses using a regex". Codex reads your project's language settings, produces an idiomatic implementation, and writes the output to stdout by default. Add --write to write directly to a file, or --clipboard to copy the result for pasting into your editor. The --lang flag overrides the project default — codex generate "email validator" --lang rust produces Rust output even in a JavaScript project. The CLI supports piping: codex generate "parse CSV" | tee parser.py works exactly as expected. Every generation includes a confidence score and a brief explanation of design decisions — the score helps you decide whether the output needs manual review. The CLI also supports multi-file generation: codex scaffold "REST API with users and posts" creates a directory structure with models, routes, controllers, and tests, all wired together with correct imports.

We asked senior engineers who adopted the Codex CLI in production environments about their experience. Ingrid L. Sørensen, Senior Backend Architect at Polaris Networks in New York, described the transition: "We rolled out Codex CLI across a 47-person engineering org in a single afternoon. The Homebrew install worked on every Mac without a single support ticket. By the following Monday, our team was generating entire microservice skeletons from the terminal, and the code passed our CI checks on the first push more often than not. The shell completion alone saves me fifteen minutes a day." Her team subsequently integrated Codex into their pre-commit hooks, where it runs automated linting and security checks on every staged change.

Troubleshooting Common Installation Issues

Most installation hiccups trace back to PATH configuration or permission issues. The fixes are mechanical and well-documented.

If codex is not found after installation, the package manager's binary directory is likely missing from your PATH. Run npm bin -g, brew --prefix, or pip show codex-cli to locate the binary, then add that directory to your shell's PATH. If you encounter permission errors on Linux, avoid using sudo with npm — instead, configure npm to use a user-level prefix: npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH. On macOS, if Homebrew fails with a formula not found error, run brew update to refresh the package index and try again. On Windows, if PowerShell refuses to run codex due to execution policy, open PowerShell as Administrator and run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser. For proxy-related issues — common in corporate environments — set HTTP_PROXY and HTTPS_PROXY environment variables; the CLI respects standard proxy conventions. The NIST IT Laboratory publishes general guidance on secure software installation practices that complement the Codex-specific steps outlined here.