Codex CLI

Open-source CLI client for the new Codex agent. Local CLI that orchestrates cloud Codex models against your file tree.

Install via npm: npm install -g @openai/codex-cli. Requires Node.js 18+. Authenticate: codex login opens a browser for OpenAI OAuth. Alternatively, set OPENAI_API_KEY as an environment variable. Codex CLI is OpenAI's lightweight terminal coding agent — it reads your codebase, answers questions, and makes edits. Run in your project directory: cd /path/to/project && codex. Usage: codex "What does this project do?" for analysis, codex "Add input validation to src/api.ts" for editing. Codex CLI uses OpenAI's models (default GPT-5, configurable) with a tool-use system for file reading, writing, shell execution, and web search. It maintains a session context and can reference your git history. For complex multi-step tasks, Codex CLI plans and executes autonomously. Verify: codex "list the files in this directory" — it runs ls and displays results. First run: ~5 seconds for npm install, + model latency per request. Time-to-first-action: ~10 seconds including API latency. Codex CLI is optimized for UNIX-like environments (macOS, Linux, WSL2). It respects .gitignore and .codexignore for file exclusion.

Best for: OpenAI-ecosystem developers who want a first-party terminal coding tool, quick codebase analysis and Q&A ("What does this codebase do?"), lightweight editing tasks that don't require complex multi-file orchestration, prototyping and exploration where you want fast OpenAI model access from the terminal, teams already standardized on OpenAI APIs who want a consistent model experience across their tools. Not suited for: complex multi-step refactors requiring deep reasoning across many files (use Claude Code), git-centric diff-review workflows (use Aider), IDE-integrated agentic coding (use Cline or Cursor), non-OpenAI model preference (Codex CLI is OpenAI-only), offline/local-first development (Codex CLI requires OpenAI API connectivity).

Use Codex CLI when you're in the OpenAI ecosystem, want a lightweight terminal agent, and prefer the simplicity of a single codex command over multi-mode agent tools. It's the official OpenAI-backed terminal coding tool and gets priority access to new OpenAI models and features. Switch to Claude Code when code reasoning quality matters more than provider convenience — Claude Code's reasoning depth is generally better at complex multi-file refactors. Use Aider for git-native pair programming with explicit diff review — Codex CLI is more autonomous and less git-centric. Use Cursor for an IDE-native experience — Codex CLI is terminal-only. Use Cline for a VS Code agentic extension. Codex CLI's strength: direct OpenAI integration with minimal abstraction, simple mental model (one command), and lightweight resource usage. Its weakness: narrower feature set compared to Claude Code, OpenAI-only model selection, less mature permission model.

Problem: Error: OPENAI_API_KEY is not set. Fix: Run codex login for browser-based OAuth (stores token locally). If using an API key directly, ensure the format is correct: sk-... or sk-proj-... for project-scoped keys. For organization-scoped keys, prefix the org ID: OPENAI_API_KEY=sk-... OPENAI_ORG_ID=org-... codex. Problem: Codex uses the wrong model (older/cheaper) and results are poor. Fix: Codex CLI's default model is the current fastest GPT model, not necessarily the most capable. Override: codex --model gpt-5 "complex refactoring task". Model pricing differs significantly — check your OpenAI usage dashboard after heavy use. Problem: Edits corrupt files or introduce syntax errors on large files. Fix: Codex CLI replaces file content by matching context strings. If the file has very similar code blocks, the replacement can target the wrong location. Break large edits into smaller, specific instructions: "In the function handleLogin in src/auth.ts, add..." rather than "Add login validation to auth.ts." Review diffs with git diff after each Codex session.