OpenAI Codex CLI: Complete Guide for Developers in 2026

What Is Codex CLI, Really?

OpenAI Codex CLI is a terminal-native AI coding agent — not a VS Code extension, not a web app, but a command-line tool that operates directly in your terminal. Announced in early 2026, it represents OpenAI's take on the "coding agent in your terminal" workflow popularized by Claude Code.

The key distinction: Codex CLI works where you already work — your shell. No editor plugins, no GUI. You describe what you want in natural language, and Codex CLI reads your files, writes code, runs commands, and iterates.

What It's Good At

- Quick prototyping — From idea to working code in minutes - File manipulation — Create, edit, refactor files directly - Terminal commands — Runs shell commands for you (install deps, run tests, git operations) - Iterative development — You can refine by saying "change this" or "add that" - Cross-platform — Works on macOS, Linux, and Windows (WSL2)

What It's Not

- It's not a VS Code extension or editor plugin - It's not a replacement for your IDE's autocomplete - It's not a multi-file refactoring tool (though it can edit multiple files)

---

Installation

Prerequisites

- Node.js 18+ (for npm-based install) - Python 3.10+ (Codex CLI has a Python backend) - Git (for repository operations) - OpenAI API key with access to GPT-4o or newer models - Operating System: macOS 13+, Linux (Ubuntu 22.04+, Debian 12+, etc.), or Windows via WSL2

Install via npm

npm install -g @openai/codex

Verify the installation:

codex --version

Install via pip (alternative)

pip install openai-codex

Both packages install the same codex command, so pick whichever fits your toolchain.

Set Your API Key

export OPENAI_API_KEY="sk-proj-your-key-here"

Add it to your shell profile for persistence:

# For bash
echo 'export OPENAI_API_KEY="sk-proj-your-key-here"' >> ~/.bashrc
# For zsh
echo 'export OPENAI_API_KEY="sk-proj-your-key-here"' >> ~/.zshrc

---

First Run

Navigate to a project directory and start Codex CLI:

cd ~/projects/my-app
codex

You'll see a prompt like:

Codex CLI v1.2.0
Connected to: gpt-4o (model: gpt-4o)
Working directory: /home/user/projects/my-app
> 

Type your first request:

> create a simple Express.js server with a /health endpoint

Codex CLI will: 1. Check if project has package.json (if not, offer to initialize) 2. Install Express if needed 3. Create the server file 4. Start the server in the background 5. Show you the result

This is where Codex CLI shines — it handles the whole cycle: install, code, run, verify.

---

Core Workflows

Workflow 1: Scaffold a Full Project

Codex CLI excels at getting a project off the ground:

> create a Next.js 15 app with TypeScript, Tailwind CSS, 
  and a basic blog layout (header, blog list, footer). 
  Use the app router. Don't install extra deps beyond what's needed.

What happens:

1. Codex runs npx create-next-app@latest with your choices 2. Configures TypeScript and Tailwind 3. Creates layout, page components, and styles 4. Installs dependencies 5. Reports ready status

Real talk: It works 80% of the time on first try. The other 20%, you'll need to guide it — "the header needs to be sticky" or "use css modules instead of tailwind".

Workflow 2: Add a Feature

This is where Codex CLI beats both manual coding and other AI tools:

> add user authentication to this Next.js app. Use next-auth v5 
  with GitHub and Google providers. Create a sign-in page at /auth/signin 
  and protect the /dashboard route.

Codex will: 1. Install next-auth and configure the providers 2. Create the auth route handler ([...nextauth]) 3. Create the sign-in and callback pages 4. Set up middleware for route protection 5. Create a session provider wrapper

The key advantage: Codex CLI reads your existing code to understand your patterns, then writes code that's consistent with your project.

Workflow 3: Debugging

When you hit a bug, don't search Stack Overflow — just describe it:

> the /api/users endpoint returns 500. here's the error:
  "Cannot read properties of undefined (reading 'id')". 
  check the route handler in src/app/api/users/route.ts and fix it.

Codex reads the file, finds the bug, and fixes it. If it needs to run npm test or curl to verify, it will.

Workflow 4: Code Explanation

> explain this function in src/utils/parser.ts line by line. 
  I don't understand how the recursive parsing works.

Codex explains in context, referencing actual line numbers. This is genuinely useful for onboarding onto new codebases.

---

Configuration

Setting Default Parameters

Codex CLI uses a configuration file at ~/.config/codex/config.json:

{
  "model": "gpt-4o",
  "temperature": 0.2,
  "maxTokens": 8192,
  "maxRounds": 30,
  "theme": "dark",
  "autoApproveCommands": ["npm install", "pip install", "git add"]
}

Key settings:

| Setting | Default | Description | |---------|---------|-------------| | model | gpt-4o | Model to use. gpt-4.1 also available | | temperature | 0.2 | Lower = more deterministic, higher = more creative | | maxTokens | 8192 | Max tokens per response | | maxRounds | 30 | Max conversation turns before forcing a summary | | autoApproveCommands | [] | Commands to auto-approve without asking | | theme | dark | dark, light, or auto |

Project-Level Configuration

You can also configure Codex CLI per project by creating a .codex.json file in your project root:

{
  "instructions": [
    "Use TypeScript strict mode",
    "ESLint rules must pass",
    "Write tests for new functions",
    "Use zustand for state management"
  ],
  "ignorePaths": ["dist/", ".next/", "node_modules/"],
  "conventions": {
    "components": "src/components/",
    "pages": "src/app/",
    "utils": "src/lib/"
  }
}

This tells Codex CLI about your project's structure and coding conventions. It's the equivalent of .cursorrules or .clinerules.

---

Codex CLI vs Claude Code: Honest Comparison

I use both daily. Here's the unvarnished truth about when to use which.

Codex CLI Wins

| Area | Why | |------|-----| | Quick prototypes | Faster iteration, less latency | | npm/Python projects | Better at understanding package ecosystems | | Code generation | Tends to write more complete, production-ready code | | Output quality | GPT-4o generates cleaner initial code | | Windows support | Works natively in WSL2, no Anthropic account needed |

Claude Code Wins

| Area | Why | |------|-----| | Deep refactoring | Better at understanding complex codebases | | Terminal UX | Claude Code's session management is more mature | | Multi-file changes | More reliable at coordinating cross-file edits | | MCP integration | Anthropic's MCP ecosystem is richer than OpenAI's equivalent | | Cost | Claude Sonnet is cheaper for longer sessions | | Autonomy | Claude Code's --bypassPermissions mode for fully unattended runs |

The Rule of Thumb

- Quick tasks (under 10 minutes) → Codex CLI - Deep tasks (30+ minutes of complex work) → Claude Code - Learning new codebases → Codex CLI (better explanations) - Large refactors → Claude Code (better context management)

This isn't going to stay static. Both tools are iterating fast. But as of mid-2026, this split holds up in daily use.

---

Advanced Techniques

1. Multi-Session Strategy

Don't put everything in one long conversation. Instead:

Session 1: "Set up project structure with Next.js, auth, and database schema"
Session 2: "Create the API routes for users and posts"
Session 3: "Build the frontend components for dashboard"

Each session starts fresh with focused context. This avoids context window issues and gives better results per dollar.

2. Using .codexignore

Prevent Codex from wasting context on generated files:

# .codexignore
.next/
node_modules/
dist/
*.generated.ts
*.min.js
package-lock.json

3. Command Approval Mode

By default, Codex CLI asks before running every command. For trusted projects:

{
  "autoApproveCommands": [
    "npm install *",
    "pip install *",
    "git add -A",
    "git commit -m *",
    "npx prettier --write *"
  ]
}

⚠️ Only do this in projects you trust. A malicious model response could run destructive commands.

4. Working with Existing Tests

Codex CLI understands testing frameworks. Use it to:

> look at the existing tests in __tests__/ and write tests 
  for the remaining untested utility functions in src/lib/. 
  Match the existing testing style (vitest + testing-library).

It'll scan your test files, infer the patterns, and write consistent tests.

5. Git Workflow Integration

Codex CLI can work with your git workflow naturally:

> git status shows I have 3 modified files. Group these changes 
  into separate commits with meaningful messages.

It'll stage and commit files in logical groups.

---

Common Pitfalls (From Real Usage)

❌ "Codex keeps going in circles"

Problem: Codex writes code that doesn't work, then tries to fix it, but breaks something else.

Fix: Say "stop, let me check the current state" and then provide a correction. Or use a shorter maxRounds limit.

❌ "The context got confused"

Problem: After 20+ exchanges, Codex starts forgetting earlier requirements.

Fix: Start a new session and be more specific about requirements from the start. Or use .codex.json to set project-level instructions.

❌ "It keeps adding things I didn't ask for"

Problem: Codex tends to add features beyond the scope of your request.

Fix: Be explicit: "Only create the API route, don't modify any existing files" or "Minimal implementation — no extra features."

❌ "File for file operations"

Problem: Codex uses a file-based approach where it reads/writes entire files. For large files, this is slow and expensive.

Fix: For large files, break down your task into smaller, targeted changes: "Change the fetchUser function in line 45 of user.ts" rather than "Update the user module."

❌ "The API key costs are adding up"

Problem: Verbose responses and unnecessary file reads inflate token usage.

Fix: - Use temperature: 0.1 for straightforward tasks (less output randomness) - End sessions when done (don't let idle conversations accumulate) - Set a max cost: codex config set maxCost 10

---

When NOT to Use Codex CLI

Let's be honest about the scenarios where Codex CLI is the wrong tool:

1. If you want inline code suggestions → Use GitHub Copilot or Cursor 2. If you're doing visual design work → Use Cursor with Claude, or Windsurf 3. If you need deep project-wide refactoring → Use Claude Code 4. If you're offline → Use Ollama + Continue.dev 5. If you have strict compliance requirements → Self-hosted solutions only

Codex CLI is a terminal agent, not a universal IDE. Use it where it fits.

---

The Bottom Line

OpenAI Codex CLI in mid-2026 is a very capable tool for the right job. It's best for:

- Starting projects from scratch - Adding well-defined features to existing projects - Debugging and code explanation - Quick prototyping and experimentation

It's not a silver bullet, and it won't replace your editor or Claude Code for deep work. But as a second tool in your AI coding arsenal, it's indispensable.

Price: Free (you pay for OpenAI API usage). A typical session costs $0.50–3.00 depending on complexity.

Try it: npm install -g @openai/codex and run codex in your next project. Spend 15 minutes with it and you'll know immediately if it fits your workflow.

---

Want to compare more AI coding tools? Read our complete AI coding assistant comparison or see how Codex stacks up against Claude Code and Cline.