What is Codex CLI? A Complete Guide to OpenAI's Terminal AI Coding Assistant

Essential Reading Updated May 28, 2026 ~10 min read

OpenAI released a terminal-native AI coding assistant — not a chat window in a browser, but a true Agent that can read and write your local files, execute shell commands, and complete multi-step tasks autonomously. This guide explains what it is, what it does, and how it differs from ChatGPT.

TL;DR

Codex CLI is OpenAI's open-source terminal-native AI assistant. It runs directly in your command line, reads and writes files, executes shell commands, and calls external APIs — essentially the "hands-on" version of ChatGPT.

Core Positioning of Codex CLI

Many developers first hear about Codex CLI and assume it's just a terminal interface for ChatGPT — both are from OpenAI, both answer programming questions. But the two are fundamentally different:

  • ChatGPT is a conversation interface: You type in a browser, it sends back text. That's the full extent of it.
  • Codex CLI is an AI Agent: It runs inside your terminal and can directly operate on your computer.

OpenAI officially describes it as "a lightweight coding assistant that executes tasks in the terminal". Specifically, it can:

  • Read and modify local files without manual copy-pasting
  • Execute arbitrary bash/shell commands
  • Call external tools and APIs
  • Complete complex multi-step tasks autonomously, pausing to confirm critical operations
bash — Basic Codex CLI usage examples
# Ask Codex to write code for you
$ codex "write a Python scraper to fetch Hacker News front page titles"

# Ask it to fix a bug
$ codex "there's an off-by-one error in this code, please fix it" --file main.py

Codex CLI was open-sourced by OpenAI in April 2025 under the MIT license. Anyone can use and modify it freely (calling the API does consume OpenAI tokens).

Differences from ChatGPT / Claude

A single table to illustrate the core differences between all three:

Dimension ChatGPT (Web) Codex CLI Claude Code
Environment Browser Terminal Terminal
File Access Requires upload Direct local read/write Direct local read/write
Execute Commands ✗ ✓ ✓
Open Source ✗ ✓ (MIT) ✗
Pricing ChatGPT subscription API tokens Claude subscription / API
Best For Conversational Q&A Automation / coding tasks Complex project development
i

For a detailed comparison of model capabilities, pricing, and use-case fit, see the Codex CLI vs Claude Code page.

Core Features Overview

Codex CLI is more than a "terminal ChatGPT" — it ships with a set of developer-focused engineering features:

  1. Multi-model support: Defaults to o4-mini, but also supports o3, GPT-4.1, and others via the --model flag. Different models offer different trade-offs between speed, cost, and reasoning depth.
  2. Sandbox isolation: File reads, writes, and command execution each have configurable permission levels (read-only / write / execute), with optional Docker-based isolation for high-risk operations.
  3. Multimodal input: Pass screenshots or images via the --image flag. Codex can analyze UI screenshots or error screenshots and provide actionable suggestions.
  4. Context awareness: Codex automatically reads AGENTS.md or CODEX.md from the project root, picking up project-specific instructions, coding conventions, and background context.
  5. Session management: Use /history to review past conversations and --resume to restore the last session — ideal for multi-day, ongoing tasks.
  6. Fully open source: MIT license. Full source code on GitHub — inspect, modify, or extend it however you like.

Typical Use Cases

Codex CLI delivers the biggest productivity gains in these scenarios:

🐛

Debugging Code

Paste an error message and Codex pinpoints the root cause, proposes a fix, and applies it to your file after confirmation.

📝

Writing Scripts

Describe what you need in plain English and get a runnable bash or Python script — no boilerplate writing required.

🔍

Code Review

Run codex "review this code for security issues" for a quick scan of vulnerabilities and potential problems.

📁

File Operations

Bulk rename files, convert formats, extract content — describe it in one sentence and Codex handles all the files.

🚀

DevOps Assistance

Generate Dockerfiles, GitHub Actions workflows, and CI/CD configurations. Infrastructure-as-code made simpler.

📖

Documentation Generation

Automatically generate JSDoc / Python Docstring comments for functions and classes, plus complete README files.

How It Works

Understanding how Codex CLI operates helps you use it more effectively and anticipate its capabilities and limits:

Codex CLI execution flow
Your terminal → codex CLI → OpenAI API (o4-mini)
                   ↓              ↓
          Local execution  ←  Tool call instructions
         (bash / file ops)

The full loop works like this:

  1. You enter a task description in the terminal. Codex CLI packages the request (with context) and sends it to the OpenAI API.
  2. The model returns a response along with structured "tool call instructions" (e.g., read a specific file, run a specific command).
  3. Codex CLI executes those tool calls locally — reading/writing files, running shell commands, etc.
  4. The execution results are sent back to the model, which decides the next action based on the outcome.
  5. This loop continues until the task is complete or the model requires your confirmation.
Note

Codex CLI requires your confirmation before executing commands (controlled by the approval_policy parameter). By default, it will not silently run high-risk operations (such as deleting files or modifying system configurations). You can adjust the approval policy via configuration.

Quick Start in 5 Minutes

Follow these steps to install Codex CLI and run your first task in under 5 minutes:

  1. Install: Make sure Node.js 22+ is installed, then run:
    bash
    $ npm install -g @openai/codex
  2. Log in: Run codex login and follow the prompts to configure your OpenAI API Key (obtain one from platform.openai.com).
  3. Launch: Navigate to any project directory and run codex to enter the interactive interface.
  4. Send your first task: Try typing ls -la or "write a Python script that prints Hello World" and watch how Codex responds and executes.

Need more installation details (Node.js version requirements, Homebrew installation, common errors)? See the complete installation guide. First-run and login configuration details are in Login & First Run.

Frequently Asked Questions

What is the difference between Codex CLI and GitHub Copilot?

The two tools have fundamentally different purposes. GitHub Copilot integrates into editors like VS Code and JetBrains to provide inline code completion — you write half a line and it suggests the rest.

Codex CLI runs in the terminal and acts as an autonomous Agent. You give it a goal (e.g., "refactor this module"), and it can read files, execute commands, and modify code on its own until the task is done. It's better suited for automation, batch processing, and complex multi-step tasks.

Does Codex CLI require an internet connection?

Yes. Codex CLI relies on the OpenAI API for every request and requires an active internet connection to function. There is currently no offline or local-model support.

Users in mainland China face network restrictions and will need to configure a proxy to reach the OpenAI API. See the Reconnecting & Proxy Guide for details.

Is Codex CLI safe? Will it send my code to OpenAI?

Code snippets and instructions you provide are transmitted to OpenAI's servers for processing — this is a necessary part of how it works.

Regarding privacy: OpenAI does not use API request data to train models by default, but you should confirm and enable this in your privacy settings at platform.openai.com. For sensitive code (API keys, proprietary algorithms), create a .codexignore file in the project root to exclude those files from being sent.

Can I use Codex CLI on Windows?

Yes. The recommended approach on Windows is via WSL2 (Windows Subsystem for Linux), which provides the best compatibility and experience. Simply follow the Linux installation steps inside your WSL2 environment.

Running directly in PowerShell or CMD is also possible, but some bash-dependent features may be limited. WSL2 network proxy configuration requires extra attention — see WSL2 Network Configuration for details.

Is Codex CLI the same as the old OpenAI Codex model?

No, they are completely different products:

The old "Codex" referred to OpenAI's code-davinci-002 language model — the underlying model powering early GitHub Copilot — which was officially deprecated in March 2023.

Codex CLI is a brand-new open-source command-line tool released in April 2025, powered by modern models like o4-mini. It shares only the name with the old Codex model; the architecture, functionality, and purpose are entirely different.