CLI Setup

tutorialbeginner5 min readVerified Mar 8, 2026

Install and configure the Codex CLI for terminal-native development. Covers npm/brew installation, authentication, config.toml basics, and your first task.

codexcliinstallationterminalsetup

CLI Setup

The Codex CLI is a terminal-based coding agent that reads, edits, and runs code on your machine. It is open source, built in Rust for speed, and shares configuration with the IDE extension and desktop app.

Installation#

You have three installation options:

Option 1: npm (Recommended)#

npm i -g @openai/codex

Requires Node.js 18 or later.

Option 2: Homebrew (macOS)#

brew install --cask codex

Option 3: Direct Binary#

Download the latest binary for your platform from the GitHub Releases page.

Authentication#

After installation, run codex and choose your auth method:

Sign in with ChatGPT (Recommended)#

codex
# Select "Sign in with ChatGPT"
# Follow the browser prompt to authenticate

This uses your ChatGPT plan credits (Plus, Pro, Business, Edu, or Enterprise).

Use an API Key#

export OPENAI_API_KEY="sk-..."
codex

Or set it permanently in your shell profile. API usage is billed at standard rates.

First Run#

Navigate to a project directory and launch Codex:

cd ~/my-project
codex

Codex opens a full-screen terminal UI (TUI) where you can:

  • Type natural language prompts
  • Review proposed changes before they are applied
  • Watch Codex run commands in real time
  • Use slash commands like /review, /diff, /theme
Tip

Try a simple first task: codex "Explain the structure of this project" — this helps you verify that Codex can read your codebase correctly.

## Choosing a Model

By default, Codex uses GPT-5.4. You can switch models:

# Use GPT-5.3-Codex for intensive coding
codex -c model="gpt-5.3-codex"

# Use Spark for quick edits (Pro plan only)
codex -c model="gpt-5.3-codex-spark"

Or set it permanently in ~/.codex/config.toml:

model = "gpt-5.4"

Basic Configuration#

The CLI reads settings from ~/.codex/config.toml. Here is a starter config:

# Model selection
model = "gpt-5.4"

# Safety: pause before running risky commands
approval_policy = "on-request"

# Sandbox: allow writes only in workspace
sandbox_mode = "workspace-write"

See Configuration for the full reference.

Useful Commands#

| Command | Description | |---------|-------------| | codex | Launch interactive TUI | | codex "prompt" | Start with a specific task | | codex exec "prompt" | Non-interactive mode for scripts | | codex resume | Resume a previous session | | codex mcp add | Add an MCP server | | codex --image file.png "prompt" | Attach an image to your prompt |

Platform Notes#

  • macOS: Full support with native seatbelt sandbox
  • Linux: Full support with Landlock sandbox (optional bubblewrap)
  • Windows: Use WSL for best results. Native Windows has experimental support

Next Steps#

PreviousCodex ResourcesNextImage to Code