This is Part 1 of the Codex CLI series. We’ll cover installation, authentication, and your first session. Future posts will explore workflows, best practices, and advanced features.
Codex CLI Overview: Terminal-Based AI Coding Agent
Today I want to introduce you to Codex CLI—a tool that has genuinely changed how I work with both code and writing.
If you have ever wished you could have an AI assistant that actually understands your project, can read your files, and help you make changes right from your terminal, Codex CLI is exactly that. It is not just another chatbot; it is designed to work inside your repository, understanding your code structure and helping you improve it safely.
In this series, I will walk you through everything you need to know to use Codex CLI productively. Today’s post covers the fundamentals: what it is, how to install it, and how to take your first steps safely.
What Is Codex CLI?
Before we jump into installation, let me explain what Codex CLI actually is and why it is different from using ChatGPT in a browser.
The Core Concept
Codex CLI is a coding agent that runs locally in your terminal. When you start it in a project directory, it can:
- Read all the files in that directory
- Understand your project structure
- Propose changes to files
- Run commands (with your approval)
- Show you diffs before applying changes
Think of it as having an experienced developer pair-programming with you, but one who works incredibly fast and has read your entire codebase. See the [official Codex CLI documentation][1] for the complete command reference.
How It Differs from ChatGPT
Here is a helpful comparison:
ChatGPT in a browser:
- Great for discussing ideas and getting code snippets
- You copy and paste code back and forth
- It does not know about your actual project files
- Every conversation starts fresh
Codex CLI:
- Understands your entire repository context
- Can directly edit your files (with approval)
- Can run tests and commands in your environment
- Maintains conversation history across sessions
The key difference is context and action. Codex CLI sits next to your actual code and can help you work with it directly.
Codex CLI vs ChatGPT: Quick-Reference
| Dimension |
ChatGPT in Browser |
Codex CLI in Terminal |
| Project context |
None — you paste snippets manually. |
Full repo read; understands file structure. |
| File editing |
You copy-paste suggestions back manually. |
Proposes and applies diffs with your approval. |
| Command execution |
Cannot run commands. |
Runs pytest, ruff, build scripts in your env. |
| Session memory |
Resets every conversation. |
Maintains history; resumable across sessions. |
| Safety model |
No guardrails on outputs. |
Approval modes: read-only → auto → full access. |
| Best for |
Ideas, snippets, brainstorming. |
Repo-native edits, QA, automation, refactors. |
The Safety Model
Here is what I appreciate most: Codex CLI is built with safety guardrails. By default, it asks for permission before:
- Editing files
- Running commands
- Making network requests
You control how much autonomy to give it through “approval modes” (which I will explain in Part 2). This means you can start conservatively and gradually trust it more as you become comfortable.
Installation Guide
Codex CLI works on macOS, Linux, and Windows. The installation method varies slightly by platform, so I will walk through each one.
Prerequisites
Before installing, you need:
- Terminal/Command line access
- An OpenAI account (ChatGPT subscription or API access)
- Node.js — only if you install via npm; the official installer script below does not need it
Quick Install: The Official Installer Script
OpenAI now ships a one-line installer that works the same way on macOS and Linux, and does not require Node.js or a package manager at all. If you just want Codex CLI running in the next thirty seconds, this is the fastest route:
# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
The script downloads the right prebuilt binary for your platform and puts codex on your PATH. Verify it worked with codex --version, then update any time with codex update — that command works regardless of which install method you used.
If you would rather manage Codex through a package manager you already use — Homebrew keeping it updated via brew upgrade, or npm alongside your other global tools — the platform sections below cover both.
How to Install Codex CLI on macOS (Apple Silicon and Intel)
Beyond the quick installer script above, Mac users have two package-manager options: Homebrew (easiest to keep updated) or npm (universal).
Option 1: Homebrew (Recommended)
If you use Homebrew, this is the simplest path:
# Install Codex CLI
brew install --cask codex
# Verify installation
codex --version
# Launch it
codex
Why this works well: Homebrew handles all dependencies and keeps Codex updated automatically when you run brew upgrade. Cask details: [Homebrew Formulae: codex][3].
Option 2: npm
If you prefer npm or already manage tools through Node:
# Install globally via npm
npm install -g @openai/codex
# Verify installation
codex --version
# Launch it
codex
When to use this: If you manage development tools through npm or want consistent installation across all your machines. Package details: [@openai/codex on npm][2].
My Codex CLI version that I have used to write this post is:
How to Install Codex CLI on Linux
Linux users can use the quick installer script above — it is now the simplest path, since it skips the Node.js requirement entirely. If you prefer npm, or already manage tools through Node, that remains fully supported too, with manual binaries as a further alternative.
npm Installation
# First, ensure you have Node.js installed
# Ubuntu/Debian:
sudo apt install nodejs npm
# Fedora:
sudo dnf install nodejs npm
# Arch:
sudo pacman -S nodejs npm
# Install Codex CLI globally
npm install -g @openai/codex
# Verify installation
codex --version
Manual Binary Installation
Manual binary installation is useful for CI/CD environments or systems where npm is not available:
- Download from GitHub releases
- Choose
codex-linux-x64 for Intel/AMD
- Choose
codex-linux-arm64 for ARM
- Extract and install:
# Example for x64
wget https://github.com/openai/codex/releases/download/vX.X.X/codex-linux-x64.tar.gz
tar -xzf codex-linux-x64.tar.gz
# Move to a directory in your PATH
sudo mv codex /usr/local/bin/
# Make executable
sudo chmod +x /usr/local/bin/codex
# Verify
codex --version
How to Install Codex CLI on Windows (WSL2 Recommended)
For Windows users, I strongly recommend using WSL2 (Windows Subsystem for Linux). While Codex can run natively on Windows, WSL2 provides better performance and fewer compatibility issues.
Why WSL2?
WSL2 gives you a Linux environment on Windows with (full setup instructions: [Install WSL — Microsoft Learn][4]):
- Better file operation performance
- Fewer permission issues
- Compatibility with Linux development tools
- More predictable behavior
Setting Up WSL2
If you do not have WSL2 yet:
-
Open PowerShell as Administrator
-
Install WSL2:
# Install WSL2 and Ubuntu
wsl --install
# Restart your computer when prompted
-
After restart, open WSL (it will finish setup automatically)
-
Install Node.js in WSL:
# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# Close and reopen your terminal, then:
nvm install 22
# Verify
node --version
npm --version
- Install Codex CLI:
npm install -g @openai/codex
# Verify
codex --version
Important WSL Best Practice
Keep repositories in your Linux home directory (~/code/myproject), not under Windows paths (/mnt/c/Users/...).
Why? File operations are significantly faster, and you avoid permission and line-ending issues.
# Good: Fast and reliable
mkdir -p ~/code
cd ~/code
# Avoid: Slower, potential issues
cd /mnt/c/Users/YourName/Documents/code
Tip: You can still access WSL files from Windows Explorer by typing \\wsl$\Ubuntu in the address bar.
Fixing Common Codex CLI Installation Errors
Two errors account for most of the friction developers hit right after installing Codex CLI.
“zsh: command not found: codex” or “bash: codex: command not found”
Cause: npm’s global bin directory (where codex gets symlinked) is not on your shell’s PATH.
Fix:
# Find npm's global bin directory
npm config get prefix
# Add it to your PATH (adjust the path to match the output above)
export PATH="$(npm config get prefix)/bin:$PATH"
# Make it permanent by adding the line above to ~/.zshrc or ~/.bashrc
“npm error code EACCES” during global install
Cause: Your user account does not have write permission to npm’s default global node_modules directory, which is common on macOS and Linux when Node.js was installed via a system package manager.
Fix: Reconfigure npm to use a directory you own instead of using sudo:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
# Now retry
npm install -g @openai/codex
Authentication
🔒 Subscribe to keep reading.
Your First Session
🔒 Subscribe to keep reading.
Codex CLI Practice Checklist: Recommended First Steps
🔒 Subscribe to keep reading.
Codex CLI Series Roadmap: Parts 2–4
🔒 Subscribe to keep reading.
Codex CLI Adoption Strategy: Building Trust Gradually
🔒 Subscribe to keep reading.
