OpenAI Codex CLI: Complete Getting Started Guide

This is Part 2 of our series on AI coding assistants for developers. See also: Getting Started with Claude Code, Getting Started with Google Gemini CLI, and Comparing Claude Code, Codex, and Gemini CLI.

OpenAI's Codex CLI is a terminal-based coding agent that reads, modifies, and executes code directly on your machine. Built in Rust and fully open source, it brings OpenAI's latest reasoning models into your existing development workflow — no browser required.

Unlike the deprecated Codex API, this tool is designed for agentic coding: you describe what you want in plain English, and Codex figures out which files to change, what commands to run, and how to verify the result. Your source code stays local unless you explicitly share it — only prompts and high-level context are sent to the model.

Whether you're refactoring a legacy codebase, writing test suites, fixing bugs, or automating CI/CD pipelines, Codex CLI gives you a capable assistant that works where you already work — the terminal.

What Is Codex CLI?

Codex CLI is an open-source command-line coding agent from OpenAI. It launches a full-screen terminal interface where you can have a conversation about your codebase, ask it to implement features, fix bugs, review code, or explain unfamiliar logic.

Here's what sets it apart from browser-based AI tools:

• Local-first execution: Codex runs on your machine, reading and modifying files in your working directory. Your source code never leaves your environment.
• Agentic workflow: Rather than just generating snippets, Codex plans multi-step changes across multiple files, runs commands, and verifies results.
• Granular permissions: Three approval modes let you control exactly how much autonomy Codex has — from read-only consultation to full access.
• Session persistence: Conversations are stored locally. You can resume previous sessions with codex resume --last or codex resume <SESSION_ID>, picking up exactly where you left off.
• Built-in code review: The /review command analyses diffs against base branches, uncommitted changes, or specific commits — useful before merging or deploying.

Codex CLI is powered by gpt-5.3-codex, a model specifically optimised for software engineering tasks. ChatGPT Pro subscribers also get access to GPT-5.3-Codex-Spark, a faster variant for simpler tasks.

Key Features

A quick overview of what Codex CLI brings to the table:

• Multi-file editing: Codex understands project structure and can coordinate changes across multiple files in a single operation — renaming a function, updating its callers, and adjusting the tests.
• Command execution: Beyond editing code, Codex can run shell commands (build steps, test suites, linters) and react to the output, fixing issues iteratively.
• Image input: Pass screenshots, wireframes, or diagrams alongside text prompts to generate matching code.
• Pipe-friendly: Accepts stdin input, so you can pipe Git diffs, logs, or other command output directly into Codex for analysis.
• MCP integration: Connect to external tools and services via the Model Context Protocol for capabilities like GitHub PR management, database queries, or file system operations.
• Multi-agent orchestration: Run multiple Codex agents in parallel on isolated Git worktrees for large-scale refactoring or migration tasks (experimental).
• Headless mode: The codex exec command runs without an interactive UI, making it suitable for CI/CD pipelines and scripted automation.
• Custom instructions: Project-level AGENTS.md files let you encode coding standards, architecture decisions, and deployment rules that Codex follows automatically.

How Does It Compare to Other AI CLI Tools?

If you're evaluating terminal-based coding assistants, here's a quick comparison:

For a detailed breakdown, see our full comparison of Claude Code, Codex CLI, and Gemini CLI.

Installation and Setup

System Requirements

Before installing, make sure your environment meets these requirements:

• Node.js: Version 22 or later (required for the npm package)
• Operating system: macOS and Linux are fully supported. Windows works through WSL (see below).
• RAM: 4 GB minimum; 8 GB recommended for large codebases where Codex needs to index many files
• Disk space: The npm package itself is lightweight (~50 MB), but Codex creates local session data in ~/.codex/
• Network: Required for model API calls. Codex sends prompts and context to OpenAI's servers — your source files stay local unless you explicitly include them.

Installing with npm

npm install -g @openai/codex

To upgrade to the latest version:

npm install -g @openai/codex@latest

Setting Up Codex CLI on Windows with WSL

Windows users can run Codex CLI reliably through WSL. Here's how:

1. Install WSL if you haven't already:

wsl --install

1. Open your WSL terminal (Ubuntu by default) and install Node.js:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

1. Install Codex CLI:

npm install -g @openai/codex

1. Configure authentication (see below) and run codex from within your WSL workspace. Your Windows files are accessible under /mnt/c/, but for best performance work within the WSL filesystem (e.g., ~/projects/).

Authentication

You have two options:

ChatGPT Account (Recommended): If you have a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan, Codex CLI is included at no extra cost. Run codex and follow the authentication prompts.

API Key: For headless automation or CI/CD environments:

export OPENAI_API_KEY="your-api-key-here"

To set this permanently, add it to your ~/.codex/config.toml:

preferred_auth_method = "apikey"

Getting Started

Navigate to your project directory and run:

codex

This starts an interactive session with a full-screen terminal UI. You can also pass a prompt directly for non-interactive use:

codex "Explain the structure of this project"

Approval Modes

Approval modes control how much Codex can do without asking for confirmation. You can switch modes during a session using the /permissions command.

Auto (default): Codex can read files, edit code, and run commands within your working directory. It asks permission before touching anything outside that scope or using the network. This is the right choice for most development work.

Read-only: Codex can browse your files but won't make changes or run commands until you approve. Use this when you want Codex as a consultant — for code review, architecture questions, or understanding unfamiliar code.

Full Access: Codex has unrestricted access to your machine, including network operations, without asking. Use this sparingly and only for trusted, well-defined tasks in environments you control. It's powerful for automation workflows where you've already validated what Codex will do.

Choosing Models

By default, Codex uses gpt-5.3-codex for the best balance of capability and speed. You can switch models at any time:

# Use the default GPT-5.3-Codex
codex

# Use a specific model
codex -m gpt-5

# Switch models mid-session with the /model command

ChatGPT Pro subscribers get access to GPT-5.3-Codex-Spark, a faster variant that uses less of your subscription quota — ideal for simpler tasks or when you're approaching usage limits.

What Can You Build with Codex CLI?

Refactoring and Code Modernisation

Codex shines at large-scale refactoring where changes need to propagate across many files. Describe the transformation and let it handle the mechanics:

codex "Refactor the user authentication module to use async/await
       instead of callbacks. Update all callers and their tests."

codex "Migrate our Express routes from CommonJS require() to ES module
       imports. Update the package.json type field and fix any import paths."

Writing and Fixing Tests

Point Codex at untested code and it will generate meaningful test cases based on the actual implementation:

codex "Write unit tests for src/utils/validation.ts. Cover edge cases
       for email validation, password strength, and date parsing."

When tests are already failing, Codex can diagnose and fix:

codex "Run the test suite. For any failing tests, determine whether
       the test or the implementation is wrong and fix accordingly."

Bug Investigation and Fixing

Feed Codex a bug report or error message and let it trace the root cause:

codex "Users report a 500 error when uploading files larger than 10MB.
       Find the file size limit, trace the error handling path, and fix it."

Pre-Merge Code Review

Use the built-in /review command before merging:

codex
> /review main

This analyses the diff between your current branch and main, flagging potential issues with database migrations, API changes, or breaking modifications. You can also review uncommitted changes:

codex
> /review --uncommitted

Creating CI/CD Pipeline Configurations

Codex excels at generating configuration files because it can read your project structure and tailor the output:

codex "Create a GitHub Actions workflow that runs tests on push,
       builds the application, and deploys to production on merge to main"

From Screenshot to Code

Codex supports image inputs — pass screenshots, wireframes, or diagrams alongside text prompts:

codex "Build a dashboard component that looks like this mockup" -i ./dashboard-mockup.png

This is particularly useful for turning design specifications into working components.

Git Automation and Release Management

Pipe Git output directly to Codex:

# Generate release notes from recent commits
git log --oneline v1.0.0..HEAD | codex -p "Create detailed release notes from these commits"

# Analyse changes between branches
git diff main..feature/new-api | codex -p "Summarise these changes and flag any breaking API modifications"

Using codex exec for Headless and CI Workflows

The codex exec command runs Codex without the interactive terminal UI. It takes a prompt, executes it, and exits — making it ideal for CI/CD pipelines, Git hooks, cron jobs, and scripted automation.

Basic Usage

codex exec "Update the version number in package.json to 2.1.0"

Codex processes the prompt, makes the changes, and terminates. No interactive session, no manual approval (when used with full-access mode).

CI/CD Integration

Use codex exec in GitHub Actions, GitLab CI, or any pipeline runner:

jobs:
  update_changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update changelog via Codex
        run: |
          npm install -g @openai/codex
          export OPENAI_API_KEY="${{ secrets.OPENAI_API_KEY }}"
          codex exec "Update CHANGELOG for next release based on commits since last tag"

Git Hooks

Run Codex as a pre-commit or pre-push check:

# .git/hooks/pre-push
#!/bin/bash
codex exec "Review the staged changes for security issues. Exit with code 1 if critical issues found."

Batch Processing

Combine codex exec with shell scripting for batch operations:

# Add type annotations to all Python files in a directory
for file in src/utils/*.py; do
  codex exec "Add type hints to all functions in $file"
done

The headless mode respects the same authentication (API key via OPENAI_API_KEY) and approval settings as interactive mode. For unattended execution, use --full-access to skip approval prompts.

Extending Codex with MCP

Codex supports the Model Context Protocol (MCP) for connecting to external tools and services. It supports both STDIO and HTTP transports.

Add MCP server configurations to your ~/.codex/config.toml:

[mcp]
servers = [
  { name = "github", command = "npx @modelcontextprotocol/server-github" },
  { name = "filesystem", command = "npx @modelcontextprotocol/server-filesystem /path/to/project" }
]

This enables interactions like:

> @github List open pull requests that are ready for review
> @github Create a PR from this branch to main with a summary of changes

Multi-Agent Workflows

One of Codex CLI's most powerful capabilities is experimental multi-agent support. You can run multiple Codex agents in parallel on the same repository, each working in isolated Git worktrees to avoid conflicts.

This is configured in config.toml with role assignments, and it integrates with the OpenAI Agents SDK for:

• Parallel task execution: Multiple agents working on different parts of a codebase simultaneously
• Orchestration: Running Codex as an MCP server that other tools can call
• Auditable handoffs: Full traces of what each agent did, making it easy to review and approve changes
• Scalability: From single-agent quick fixes to coordinated team-level efforts

This is still experimental, but it's a glimpse of where AI-assisted development is heading — especially for large-scale refactoring or migration projects.

Custom Instructions with AGENTS.md

Give Codex project-specific context using AGENTS.md files. Codex looks for these in multiple locations and merges them:

• ~/.codex/AGENTS.md — Your personal preferences
• Root of your repository — Shared project conventions
• Current working directory — Feature-specific instructions

Example for a web application project:

## Project Context
- Ruby on Rails application with PostgreSQL
- React frontend with TypeScript
- Deployed via DeployHQ to Ubuntu 22.04 servers

## Coding Standards
- Follow RuboCop defaults for Ruby code
- Use functional React components with hooks
- All new code must include tests
- Never commit directly to main — use feature branches

## Deployment Rules
- Always run migrations before deploying new features
- Include rollback commands in deployment scripts

Using Codex CLI in Your Deployment Pipeline

If you use an automated deployment tool like DeployHQ, Codex CLI fits naturally into your workflow. Some practical patterns:

• Pre-deployment review: Run codex exec as a build step to review diffs and flag potential issues before code ships to your servers
• Deployment script generation: Ask Codex to generate or update deployment scripts based on your infrastructure, including maintenance mode toggles, database migration steps, and rollback commands
• Post-deploy verification: Use codex exec to check deployment logs and verify that expected endpoints respond correctly

These patterns work with any CI/CD pipeline or build pipeline — Codex handles the AI reasoning while your existing tooling handles the deployment mechanics.

Codex Cloud and IDE Integration

Beyond the terminal, Codex offers two additional interfaces:

Codex Cloud (via ChatGPT): Assign tasks from the web or mobile app, and Codex works on them asynchronously in a sandboxed environment. Start a task on your phone during your commute and review the results later. The cloud and CLI experiences are integrated — you can continue work across both.

VS Code Extension: A VS Code extension (compatible with Cursor and Windsurf) brings the same capabilities into your editor with context from open files and selections.

Pricing

Codex CLI is included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans at no additional cost. If you're using API credits directly, pricing follows standard OpenAI API rates.

For teams already subscribed to ChatGPT, this makes Codex CLI one of the most accessible AI coding tools available — no separate billing to manage.

Want to streamline your deployment workflow? DeployHQ automates deploying code from Git to your servers, so you can focus on building. Get started free.

Have questions? Reach out at support@deployhq.com or find us on X/Twitter.