OpenAI Codex CLI is a powerful terminal-based AI coding agent that brings intelligent code generation and command execution directly to your Ubuntu terminal. This comprehensive guide walks you through installation, configuration, and mastery of Codex CLI.

Prerequisites

  • Ubuntu 20.04 LTS or newer
  • Python 3.8 or higher
  • pip (Python package manager)
  • OpenAI API Key (get one at platform.openai.com)
  • Git installed
  • curl or wget for downloading files

Step 1: Verify Python Installation

Before installing Codex CLI, ensure Python 3.8+ is installed on your Ubuntu system.

python3 --version
pip3 --version

If Python is not installed:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv

Verify installation:

python3 --version
# Output: Python 3.x.x

Step 2: Upgrade pip and tools

pip3 install --upgrade pip setuptools wheel

Step 3: Install Codex CLI

Install Codex CLI globally from PyPI:

pip3 install codex-cli

Verify installation:

codex --version
# Output: Codex CLI v0.147.0 (or your version)

Step 4: Configure Your OpenAI API Key

Codex CLI requires your OpenAI API key to function. You can configure it in multiple ways:

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

Make it permanent by adding to your shell profile:

# For bash users
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# For zsh users
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Method B: Configuration File

mkdir -p ~/.config/codex
nano ~/.config/codex/config.yaml

Add the following content:

api_key: "your-api-key-here"
model: "code-davinci-002"
max_tokens: 256
temperature: 0.5

Save with Ctrl + O and exit with Ctrl + X.

Step 5: Basic Usage

Get Help

codex --help
codex /help  # Alternative command inside CLI

Start Interactive Mode

codex

Inside the CLI, you can:

  • Understand your codebase — Ask questions about your project structure
  • Edit files — Modify code across your repository
  • Run commands — Execute terminal commands with AI guidance
  • Get explanations — Understand complex code logic

Example Commands

# Query the AI directly
codex "How do I create a Python function to reverse a string?"

# Understand a specific file
codex "What does src/utils.py do?"

# Interactive mode
codex
> /understand src/
> Create a test for the login function
> /help

Step 6: Advanced Configuration

Customize Settings

Edit your configuration file for advanced options:

nano ~/.config/codex/config.yaml

Key configuration options:

api_key: "your-key"
model: "code-davinci-002"          # AI model to use
max_tokens: 256                  # Maximum response length
temperature: 0.5                 # Creativity level (0-1)
timeout: 30                       # Request timeout in seconds