Codex CLI

What it is and how it works

Codex CLI is OpenAI's open-source terminal client for driving coding agents against a local file tree. It's important to be precise about what "local" means here: the CLI process itself — the loop that reads your files, proposes diffs, runs shell commands, and manages the conversation — runs on your machine, but the actual language model inference happens in OpenAI's cloud via the API (or via a ChatGPT plan, depending on how it's configured). There is no local model weight loading, no GPU inference, and no offline mode. This distinguishes it sharply from tools in RunLocalAI's usual wheelhouse; it belongs here as the client-side orchestration layer, not as an example of local inference.

Architecturally, Codex CLI follows the now-familiar agentic coding pattern popularized by tools like Claude Code: a REPL-style terminal session where the model is given tool access (read file, write file, run shell command, search) and iterates in a loop — read context, decide an action, execute it, observe the result, repeat — until the task is done or it needs human input. The CLI handles sandboxing of shell execution, diff presentation, approval prompts before destructive actions, and session/context management. Because it's Apache 2.0 licensed, the entire orchestration logic — prompt construction, tool-calling schema, sandbox policy — is inspectable and modifiable, which matters for anyone who wants to audit exactly what gets sent upstream or wants to swap in their own guardrails.

The model backing it is OpenAI's Codex-branded agentic model family served over the API, not a downloadable checkpoint. That means capability, latency, and cost are all functions of OpenAI's infrastructure and pricing, not your hardware. The CLI's job is purely to be a well-behaved, scriptable, terminal-native front end to that cloud model — file tree awareness, git-aware diffing, and command execution are the value-add on top of a bare chat API call.

Deployment patterns

For a solo developer, the typical setup is: install via npm or the released binary, export an OPENAI_API_KEY (or authenticate against a ChatGPT subscription where supported), and invoke codex inside a project directory. It behaves like a persistent pair-programming session scoped to the current repo, with configurable autonomy levels — from "suggest only" (show diffs, wait for approval) to more autonomous modes that execute shell commands and apply edits with less friction. Because there's no local inference cost, the practical constraint is API spend and rate limits rather than VRAM or RAM.

In a homelab or small-team context, Codex CLI is usually run per-developer on individual workstations rather than as a shared service — unlike a local inference server (vLLM, Ollama, llama.cpp server) there's nothing to centralize on a GPU box, since all the heavy lifting is remote. Teams instead standardize around a shared API key/org billing setup, shared config files (approval policies, sandboxing rules, allowed commands) checked into the repo, and CI-adjacent usage where Codex CLI is invoked non-interactively in scripts or pipelines for automated patch generation, given its Apache 2.0 licensing makes it straightforward to wrap and redistribute internally. Because it needs outbound network access to OpenAI's API, it's a poor fit for air-gapped or offline environments — that's a hard architectural limitation, not a configuration gap.

How it compares

The closest comparison is Claude Code, Anthropic's terminal agent, which pioneered much of the UX pattern Codex CLI follows (approval-gated file edits, shell tool use, session context management). Claude Code is generally considered more mature and battle-tested at this point, with a larger ecosystem of extensions, hooks, and community tooling; Codex CLI is newer and catching up, though it has the advantage of being fully Apache 2.0 (Claude Code's CLI wrapper is source-available but under different terms), which makes it more attractive if you want to fork or embed the orchestration logic directly.

Against Aider, another open-source terminal coding agent, Codex CLI is less configurable around model choice — Aider is explicitly model-agnostic and works with a wide range of API providers and even local OpenAI-compatible endpoints, whereas Codex CLI is built specifically around OpenAI's Codex models. Aider also has a longer track record with git-native workflows (auto-commits, conventional commit messages) that Codex CLI's newer feature set is still filling in.

Compared to GitHub Copilot Workspace or Copilot's agentic modes, Codex CLI is terminal-first and scriptable rather than IDE-embedded, which suits users who want composability with shell pipelines and CI over a GUI-integrated experience, at the cost of the tighter editor integration Copilot offers inside VS Code or JetBrains.

Best use cases and honest limitations

Codex CLI is a reasonable choice if you're already paying for OpenAI API access or a ChatGPT plan, want a scriptable, terminal-native agent, and value being able to inspect or modify the client under a permissive license. The "customizable" and "pairs with OpenAI API key" strengths noted in its own pros are real: because it's Apache 2.0, teams building internal tooling on top of an agentic coding client have a legitimate, unencumbered base to start from rather than reverse-engineering a closed client.

The honest limitations are structural, not just maturity gaps. It has zero offline capability — cloud model dependency means no work happens without network access and an API key, and every action, including reading your source files into context, ships tokens to OpenAI's servers, which is a real consideration for code under strict IP or compliance constraints. It's also, by its own ecosystem's admission, less battle-tested than Claude Code CLI, meaning rougher edges around edge-case tool failures, sandbox escapes, or long-session context handling should be expected. If you need local-only inference for privacy or offline reasons, this tool is the wrong category entirely — look at local model runners paired with something like Aider or a self-hosted OpenAI-compatible endpoint instead. If you want the most mature terminal agent experience today, Claude Code remains the more proven option, with Codex CLI worth adopting primarily if you're OpenAI-committed or want the licensing freedom to modify the client itself.

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.