OpenAI Codex CLI

OpenAI Codex CLI is a lightweight coding agent from OpenAI that runs locally on your computer. It provides multimodal inputs (text, screenshots, diagrams), a rich approvals workflow with three distinct modes, and runs entirely in your terminal for quick iteration without switching contexts.

Package Information

• Package Name: @openai/codex
• Package Type: npm
• Language: Node.js (wrapper for Rust binary)
• Installation: npm install -g @openai/codex or brew install codex
• Binary Name: codex

Core Usage

# Interactive mode (default)
codex

# Non-interactive execution
codex exec "implement a new feature"
codex e "fix this bug"

# With configuration
codex -m gpt-4
codex -c key=value

Basic Usage

The Codex CLI supports both interactive and non-interactive modes:

# Start interactive session
codex

# Execute a prompt non-interactively
codex exec "Create a Python script that sorts a list of numbers"

# Run with specific model
codex -m gpt-4 exec "Refactor this code for better performance"

# Full automation mode with sandbox
codex exec --full-auto "Fix all linting errors in the project"

Architecture

The Codex CLI is built as a multi-tool with distinct operational modes:

• Interactive Mode: Terminal UI for conversational coding sessions
• Exec Mode: Non-interactive command execution
• Protocol Mode: JSON-line communication for integration
• MCP Integration: Model Context Protocol server support
• Sandboxed Execution: Platform-specific security controls

Capabilities

Interactive Terminal Interface

The default interactive mode provides a rich terminal experience with conversation management and real-time AI assistance.

codex [OPTIONS]

Interactive Mode

Non-Interactive Execution

Execute AI prompts directly from the command line without entering interactive mode.

codex exec [OPTIONS] <PROMPT>
codex e [OPTIONS] <PROMPT>

Execution Mode

Authentication Management

Handle login and logout operations with support for ChatGPT accounts and API keys.

codex login [OPTIONS] [SUBCOMMAND]
codex logout [OPTIONS]

Authentication

Model Context Protocol (MCP) Server Management

Add, remove, and manage MCP servers for extended functionality.

codex mcp [OPTIONS] [SUBCOMMAND]

MCP Management

Protocol Communication

Run Codex as a protocol server for programmatic integration via stdin/stdout JSON-line communication.

codex proto [OPTIONS]
codex p [OPTIONS]

Protocol Mode

Session Management

Resume previous interactive sessions by ID or continue the most recent session.

codex resume [OPTIONS] [SESSION_ID]

Session Management

Development Utilities

Additional tools for shell completion, debugging, and patch application.

codex completion <SHELL>
codex debug <SUBCOMMAND>
codex apply [OPTIONS]

Development Utilities

Global Configuration Options

All commands support the following global configuration options:

-p, --profile <PROFILE>       # Use specific config profile
-c, --config <KEY=VALUE>      # Runtime configuration overrides (repeatable)

Configuration is stored in ~/.codex/config.toml and can be overridden via command-line flags or environment variables.

Exit Codes

• 0: Success
• 1: General error
• 128 + signal: Process terminated by signal (Unix only)

Environment Variables

• CODEX_HOME: Override default configuration directory (~/.codex)
• PROJECT_NAME: Specify project context
• PROJECT_VERSION: Specify project version