OpenAI's Codex CLI is an autonomous coding agent that lives in your terminal. It can read your codebase, propose edits, run tests, and even execute shell commands, depending on how much autonomy you grant it. Getting it running takes about ten minutes if you know the right sequence, and slightly longer if you hit the common pitfalls that trip up first-time users.
Prerequisites
Codex CLI requires Node.js 18 or higher, though Node 22 is the safer choice. It runs on macOS 13+, Ubuntu 22.04+, and Windows 11. On Windows, WSL2 is strongly recommended for full sandbox support, though recent releases have improved native compatibility. You also need a Git repository initialized in your project directory, because Codex uses Git context to understand structure and propose changes.
Authentication requires either a ChatGPT subscription (Plus, Pro, Business, Edu, or Enterprise) or an OpenAI API key. The ChatGPT route bills against your existing subscription. The API key route uses standard metered billing and is the better fit for CI/CD pipelines or shared team accounts.
Installation
There are four practical paths, depending on what is already on your machine.
npm (most portable):
Homebrew (macOS / Linux):
Official script (macOS / Linux, no Node required):
PowerShell (Windows):
Verify the install with codex --version. The package updates frequently, sometimes several times a month, so avoid hardcoding version numbers in scripts.
Authentication
For interactive use, launch Codex and follow the browser prompt:
For API key auth, export the key first:
Do not paste the key into shell history or committed files. Use a secrets manager or a tool like direnv to scope the key to a project directory.
First Session and Approval Modes
Start inside a Git repo and try something small:
At the prompt, type a verifiable task:
Codex will read the repo, propose a diff, explain its reasoning, and ask for confirmation. This is the default suggest approval mode. Other modes include auto-edit, which applies safe file changes without asking, and full-auto, which can run shell commands. Full-auto is designed for sandboxed CI environments, not your main development machine.
Configuration and AGENTS.md
Create an AGENTS.md file at your repo root to give Codex standing instructions: coding conventions, test commands, directories to avoid. Without this file, Codex infers everything from scratch every session, which is the root cause of most "it edited the wrong thing" complaints.
Common Pitfalls
- Installing globally with sudo creates permission conflicts on update. Use a user-owned prefix or a version manager.
- Running an outdated Node version below 18 causes subtle compatibility issues.
- Skipping AGENTS.md leaves Codex guessing at your conventions.
- Mixing ChatGPT and API key auth without tracking which is active leads to billing confusion. Check with
codex login status.
Codex CLI is genuinely capable of autonomous work, which means it is also capable of autonomous mistakes. Start with suggest mode, read the reasoning, and scale up trust gradually.