How to Install and Use Codex CLI (2026)

OpenAI's Codex CLI is a terminal-based AI coding agent that lets you use OpenAI's models to write, edit, debug, and refactor code directly from the command line. Think of it as OpenAI's answer to Anthropic's Claude Code -- a lightweight, powerful tool that works in your terminal without needing a full IDE.

This guide covers installation, configuration, everyday usage, and tips for getting the most out of Codex CLI in 2026.

What Is Codex CLI?

Codex CLI is an open-source command-line tool developed by OpenAI. It connects to OpenAI's API and provides:

Interactive coding sessions in your terminal
File reading and editing with AI assistance
Code generation from natural language descriptions
Debugging and refactoring of existing code
Shell command execution with AI-guided workflows
Multi-file project understanding

Feature	Codex CLI	Claude Code	Aider
Provider	OpenAI	Anthropic	Any (BYO key)
Default model	o4-mini	Claude Sonnet	Configurable
Open source	Yes	No	Yes
Sandbox mode	Yes	Yes	No
File editing	Yes	Yes	Yes
Shell commands	Yes	Yes	Limited
Cost	API usage	Subscription or API	API usage
IDE integration	Terminal only	Terminal only	Terminal only

Prerequisites

Before installing Codex CLI, you need:

Node.js 22+ (LTS version recommended)
npm or yarn
An OpenAI API key with access to o4-mini or GPT-4o
Git (recommended for version-controlled projects)
macOS or Linux (Windows support via WSL)

Installation

Method 1: Install via npm (Recommended)

# Install globally
npm install -g @openai/codex

# Verify installation
codex --version

Method 2: Install from Source

# Clone the repository
git clone https://github.com/openai/codex.git
cd codex

# Install dependencies
npm install

# Build and link
npm run build
npm link

Method 3: Run Without Installing

# Use npx to run without global install
npx @openai/codex "explain this project"

Configuration

Set Your API Key

# Option 1: Environment variable (recommended)
export OPENAI_API_KEY="sk-your-api-key-here"

# Add to your shell profile for persistence
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# Option 2: Pass inline
OPENAI_API_KEY="sk-your-key" codex "your prompt"

Configuration File

Create a configuration file for persistent settings:

# Create config directory
mkdir -p ~/.codex

# ~/.codex/config.yaml
model: o4-mini
approval_mode: suggest  # suggest, auto-edit, or full-auto

Approval Modes

Codex CLI has three safety levels that control how much autonomy the AI gets:

Mode	Flag	Behavior
Suggest (default)	`--suggest`	Shows proposed changes, asks for approval before any edits
Auto-edit	`--auto-edit`	Automatically applies file edits, asks approval for shell commands
Full-auto	`--full-auto`	Executes everything automatically (use in sandboxed environments only)

# Use suggest mode (safest)
codex --suggest "refactor this function"

# Use auto-edit mode
codex --auto-edit "add error handling to all API calls"

# Use full-auto mode (be careful)
codex --full-auto "set up a new Express.js project with TypeScript"

Basic Usage

Interactive Mode

Launch an interactive session in your project directory:

cd /path/to/your/project
codex

This opens a chat-like interface where you can type prompts and Codex will read your files, suggest changes, and execute commands.

One-Shot Commands

Send a single prompt without entering interactive mode:

# Ask a question about your code
codex "what does the handleAuth function do?"

# Generate code
codex "create a Python script that monitors CPU usage and sends a Slack alert when it exceeds 90%"

# Debug an error
codex "I'm getting a TypeError: Cannot read property 'map' of undefined in UserList.tsx. Fix it."

# Refactor
codex "refactor the database queries in models/user.js to use prepared statements"

Piping Input

Pipe file contents or command output into Codex:

# Explain an error log
cat error.log | codex "explain what went wrong and how to fix it"

# Review a diff
git diff | codex "review these changes for bugs or issues"

# Analyze a file
cat src/utils/auth.ts | codex "are there any security vulnerabilities in this code?"

Common Use Cases

1. Generate New Files

codex "create a REST API endpoint for user registration with:
- email/password validation
- bcrypt password hashing
- JWT token generation
- proper error handling
Save it as src/routes/auth.ts"

2. Debug Errors

# Pass the error directly
codex "fix this error:
Error: ECONNREFUSED 127.0.0.1:5432
The PostgreSQL connection is failing in src/db/connection.ts"

3. Write Tests

codex "write unit tests for src/utils/validation.ts using Jest. Cover all edge cases."

4. Refactor Code

codex "refactor src/components/Dashboard.tsx to:
1. Extract the chart logic into a custom hook
2. Add proper TypeScript types
3. Replace any with specific types"

5. Explain Code

codex "explain the authentication flow in this project. Walk through each file involved."

6. Write Documentation

codex "generate JSDoc comments for all exported functions in src/utils/"

7. Shell Automation

codex "write a bash script that:
1. Backs up the PostgreSQL database
2. Compresses the backup with gzip
3. Uploads it to S3
4. Deletes backups older than 30 days"

Advanced Configuration

Using Different Models

# Use GPT-4o for complex tasks
codex --model gpt-4o "architect a microservices system for an e-commerce platform"

# Use o4-mini for quick tasks (default, cheaper)
codex --model o4-mini "fix the typo in the README"

Custom Instructions

Create a project-specific instructions file:

<!-- codex.md in your project root -->
# Codex Instructions

## Project Context
This is a Next.js 15 application using TypeScript, Tailwind CSS, and Prisma ORM.

## Coding Standards
- Use functional components with hooks
- All functions must have TypeScript types
- Use Zod for runtime validation
- Follow the existing file naming convention (kebab-case)
- Write tests for all new utility functions

## Do Not
- Do not modify the database schema without asking
- Do not install new dependencies without approval
- Do not modify .env files

Codex CLI reads this file automatically when working in the project directory.

Environment-Specific Settings

# Set model per project using .env
echo 'CODEX_MODEL=gpt-4o' >> .env

# Set approval mode per project
echo 'CODEX_APPROVAL_MODE=auto-edit' >> .env

Codex CLI vs. Claude Code

Both are terminal-based AI coding agents. Here is how they compare:

Aspect	Codex CLI	Claude Code
Models	OpenAI (o4-mini, GPT-4o)	Claude (Sonnet, Opus)
Pricing	Pay-per-token (API)	Subscription ($20/mo) or API
Open source	Yes (Apache 2.0)	No
Sandboxing	Network-disabled sandbox	Permission-based
Context window	Up to 128K tokens	Up to 200K tokens
File editing	Diff-based patches	Inline edits
MCP support	Limited	Full
Best for	OpenAI ecosystem users	Claude ecosystem users
Community	GitHub issues	Anthropic support

When to Use Codex CLI

You prefer OpenAI models
You want an open-source tool you can modify
You need the o4-mini reasoning model for complex logic
You already have an OpenAI API key

When to Use Claude Code

You prefer Claude models (especially for long context)
You need MCP server integration
You want the subscription model over pay-per-token
You need Anthropic's extended thinking for complex refactors

Cost Management

Estimating Costs

Model	Input (per 1M tokens)	Output (per 1M tokens)	Typical Session Cost
o4-mini	$1.10	$4.40	$0.05 - $0.50
GPT-4o	$2.50	$10.00	$0.10 - $2.00
GPT-4o-mini	$0.15	$0.60	$0.01 - $0.10

Tips to Reduce Costs

Use o4-mini (the default) for most tasks
Be specific in prompts to reduce back-and-forth
Set max_tokens in your config to cap response length
Use suggest mode to review changes before they execute (avoids wasted retries)
Set spending limits in your OpenAI dashboard

Troubleshooting

Issue	Solution
`command not found: codex`	Run `npm install -g @openai/codex` again, check your PATH
`OPENAI_API_KEY not set`	Export the key: `export OPENAI_API_KEY="sk-..."`
`model not found`	Check you have access to the model in your OpenAI account
Slow responses	Switch to o4-mini or gpt-4o-mini for faster output
File edits not applying	Check file permissions and that you are in the right directory
`Node.js version too old`	Upgrade to Node.js 22+: `nvm install 22`
Sandbox errors	Try running outside sandbox: `codex --no-sandbox`

Frequently Asked Questions

Is Codex CLI free? The tool itself is free and open source. You pay for OpenAI API usage based on the tokens consumed.

Can I use Codex CLI without an OpenAI key? No. Codex CLI requires an OpenAI API key. For free alternatives, consider Aider with free-tier API keys from Google or Groq.

Does Codex CLI work on Windows? Not natively. Use WSL (Windows Subsystem for Linux) to run it on Windows.

Can Codex CLI modify any file on my system? In suggest mode (default), it asks for permission before any changes. In full-auto mode, it runs in a sandboxed environment with network access disabled for safety.

How does it compare to GitHub Copilot? Copilot is an IDE extension for inline suggestions. Codex CLI is a terminal agent for complex, multi-file tasks. They serve different purposes and can be used together.

Wrapping Up

Codex CLI is a solid terminal-based AI coding agent, especially if you are already in the OpenAI ecosystem. The open-source nature, sandbox safety features, and support for reasoning models make it a strong choice for developers who prefer working in the terminal.

If you are building AI-powered applications that generate images, video, or avatars, try Hypereal AI free -- 35 credits, no credit card required. The REST API integrates easily into any project you are building with Codex CLI.