Using the Codex CLI

Initializing Your Workspace

Before using Codex in a project, initialize it to create a default configuration file:

# Navigate to your project root
cd my-project

# Initialize Codex
codex init

This creates an AGENTS.md file in your project root. We'll cover this file in detail in Episode 6, but for now, know that it tells Codex how your project is structured and what rules to follow.

Interactive Chat Mode

Start a conversational session with your entire codebase as context:

codex chat

In chat mode, you can:

• Ask questions — "What does the auth middleware do?"
• Debug issues — "Why is this API returning 500 errors?"
• Plan architecture — "How should I structure the payment module?"
• Request changes — "Add rate limiting to all API routes"

The agent reads your files, understands the relationships between modules, and provides context-aware responses.

Direct Commands with codex do

For one-off tasks where you don't need a conversation, use the do command:

# Generate a utility script
codex do "Write a script to backup the database"

# Add documentation
codex do "Add JSDoc comments to all exported functions in src/utils/"

# Fix a specific bug
codex do "Fix the timezone bug in the date formatter"

The agent executes the task and exits immediately — no interactive session needed.

Pipeline Integration

One of Codex's most powerful features is piping data directly into it. This gives the agent immediate context from any source:

# Analyze a crash log
cat error.log | codex do "Explain this crash stack trace"

# Review a specific file
cat src/api/payments.ts | codex do "Find bugs in this code"

# Analyze test output
npm test 2>&1 | codex do "Explain why these tests are failing"

# Process build errors
npm run build 2>&1 | codex do "Fix these build errors"

Useful CLI Flags

Flag	Description	Example
--cloud	Run in a cloud container	codex do "Build app" --cloud
--dry-run	Preview without making changes	codex do "Refactor API" --dry-run
--model	Choose a specific model	codex do "Solve X" --model o3
--quiet	Suppress verbose output	codex do "Fix lint" --quiet

What's Next

In the next episode, we'll cover CLI commands and session management — how to resume interrupted sessions, use dry-run mode, and switch models for different tasks.