Leanpub Header

Skip to main content

Codex CLI: The Definitive Guide

From First Prompt to Production Workflows

This book is 100% completeLast updated on 2026-07-18

Master Codex CLI from your first prompt to production-ready AI workflows. Learn how to automate coding, streamline development, and use OpenAI's terminal-native coding agent with confidence.

Minimum price

$19.00

$29.00

You pay

Author earns

$

Also available for 1 book credit with a Reader Membership

PDF
EPUB
WEB
APP
143
Pages
About

About

About the Book

Codex CLI is OpenAI's terminal-native coding agent, capable of reading codebases, editing files, running commands, and automating entire development workflows from the command line. This book takes you from installation through mastery, covering every layer of the platform: configuration, sandboxing, skills, MCP integration, subagents, automation pipelines, and real-world production patterns. Whether you are a solo developer looking to accelerate your coding workflow or a team lead building CI/CD pipelines with AI agents, this book gives you the knowledge to use Codex CLI safely, effectively, and at scale.

Author

About the Author

Steve Publications

Steve is a technology professional with more than 20 years of experience in software development, server infrastructure, cybersecurity, vulnerability research and reverse engineering. Throughout his career, he has designed, secured, analyzed and tested complex software and infrastructure, with a particular focus on understanding how systems fail and how they can be made more secure.

Outside of work, Steve enjoys sharing knowledge with the technology community. He collaborates with researchers, industry experts and technology professionals to write practical books covering software development, cybersecurity, cloud computing, networking, DevOps, artificial intelligence and enterprise technologies. His books focus on practical learning through clear explanations, real-world examples and hands-on exercises. With more than two decades of industry experience, his goal is to help IT professionals, students and technology enthusiasts build useful skills and stay current in a rapidly changing industry.

We believe readers deserve to know how our books are created. Most of our authors are not native English speakers, so we use AI to help translate, proofread manuscripts, fix grammar, improve sentence structure and make technical explanations easier to read. AI is used as an editing tool only. It does not replace the research, technical knowledge or hands-on experience behind our books. Some of our authors also prefer to remain anonymous for privacy or professional reasons. In those cases, we publish their work under a different name. The author's name may be different, but the quality of the content and our review process remain the same.

Every book is written, reviewed and maintained by experienced technology professionals, with contributions from our private technical community of more than 400 engineers and researchers from Ukraine, Belarus and Russia. We spend far more time validating technical accuracy and keeping our content up to date than generating text. We are always interested in working with experienced professionals who have deep expertise in a particular technology or domain. If you would like to publish a book with us or help review an existing manuscript, we'd love to hear from you. Send us a message describing your area of expertise. We are especially interested in niche technologies, specialized skills and emerging topics that are underrepresented in existing technical literature.

If you look through the contents of our books, you'll see practical examples, detailed explanations and material that is regularly updated. Our goal is to publish books that professionals can actually rely on, not low-effort AI-generated content. If you ever feel that one of our books does not meet that standard, Leanpub offers a 60-day money-back guarantee. Feel free to request a refund if you are not satisfied with your purchase.

Contents

Table of Contents

From First Command to Production Workflows

  1. About This Book

Introduction

  1. What This Book Covers
  2. Who This Book Is For
  3. How to Read This Book
  4. A Note on Safety

Chapter 1: What Is Codex CLI?

  1. From TypeScript to Rust: The Evolution of Codex
  2. Architecture Overview: How Codex Works Under the Hood
  3. The Five Surfaces: CLI, Desktop, Web, IDE Extension, and Cloud
  4. When to Use Codex CLI (and When Not To)
  5. Ecosystem Context: Codex vs. Claude Code, Cursor, Copilot
  6. Acknowledging Codex CLI’s Shortcomings

Chapter 2: Installation and First Run

  1. System Requirements and Prerequisites
  2. Installing via npm, Homebrew, Install Script, or Binary
  3. Windows Installation: Native and WSL2
  4. Verifying Your Installation
  5. Your First Interactive Session

Chapter 3: Authentication and Credential Management

  1. ChatGPT OAuth Sign-In Flow
  2. API Key Authentication
  3. Enterprise Access Tokens
  4. Credential Storage: File vs. Keyring
  5. CI/CD Authentication Patterns
  6. Troubleshooting Auth Failures

Chapter 4: Configuration Deep Dive

  1. Config File Locations and Precedence
  2. Core Settings: Model, Sandbox, Approval Policy
  3. Feature Flags and Experimental Capabilities
  4. Profiles for Different Workflows
  5. Custom Model Providers (Azure, Bedrock, Ollama, OpenRouter)
  6. Enterprise Managed Configuration

Chapter 5: The Interactive Terminal Experience

  1. Starting an Interactive Session
  2. Slash Commands Reference
  3. Keyboard Shortcuts and Navigation
  4. Image Input and Visual Context
  5. Session Management: Resume, Clear, and Compact
  6. TUI Customization and Themes

Chapter 6: Sandboxing, Permissions, and Security

  1. Sandbox Modes: read-only, workspace-write, danger-full-access
  2. Approval Policies: untrusted, on-request, never, granular
  3. Auto-Review: Delegating Trust to an AI Reviewer
  4. Network Access Controls and Proxy Configuration
  5. OS-Level Sandboxing: Seatbelt, bwrap, Windows Sandbox
  6. Security Best Practices and Common Pitfalls

Chapter 7: Project Context with AGENTS.md

  1. What Is AGENTS.md and Where It Lives
  2. Writing Effective Project Instructions
  3. Layered Context: Global, Project, and Override Files
  4. Context Window Management and Token Budgeting
  5. The .codexignore File
  6. Cross-Tool Portability with AGENTS.md

Chapter 8: Skills – Reusable Task Expertise

  1. What Are Skills and How They Work
  2. The SKILL.md Format and Directory Structure
  3. Skill Discovery: Implicit vs. Explicit Invocation
  4. Creating Skills with $skill-creator
  5. Installing and Distributing Skills
  6. Best Practices for Writing Effective Skills

Chapter 9: Model Context Protocol (MCP) Integration

  1. What Is MCP and Why It Matters
  2. Configuring MCP Servers in config.toml
  3. Managing Servers via codex mcp Commands
  4. STDIO vs. Streamable HTTP Servers
  5. Tool Control: Enabling, Disabling, and Approval Modes
  6. Real-World MCP Server Recipes and Walkthroughs

Chapter 10: Subagents and Multi-Agent Orchestration

  1. How Subagents Work: Architecture and Benefits
  2. Triggering Subagents: Prompts, AGENTS.md, and Skills
  3. Custom Agent Definitions in TOML
  4. Parallel Execution Patterns and Git Worktrees
  5. CSV Batching for High-Volume Tasks
  6. Multi-Agent Best Practices and Cost Management

Chapter 11: Non-Interactive Mode and Automation

  1. codex exec: Headless Execution
  2. JSON Output and Schema Validation
  3. Session Resumption in Automated Workflows
  4. GitHub Actions Integration (openai/codex-action)
  5. Scripting Patterns and Bash Wrappers
  6. Stdin Piping and Prompt Composition

Chapter 12: Code Review and Git Integration

  1. The /review Command: Modes and Scope
  2. Pre-Commit Review Workflows
  3. GitHub Pull Request Reviews with @codex review
  4. Branch and Commit Inspection
  5. Git Checkpoint Strategies
  6. Custom Review Guidelines

Chapter 13: Codex Cloud and Remote Execution

  1. What Is Codex Cloud and When to Use It
  2. codex cloud Commands: exec, list, apply
  3. Cloud Environment Setup Scripts and Container Caching
  4. Remote SSH Connections
  5. Best-of-N Attempts and Retry Strategies
  6. Cloud vs. Local: Decision Framework

Chapter 14: Model Selection and Reasoning Configuration

  1. The GPT-5.6 Family: Sol, Terra, Luna
  2. Legacy Models: GPT-5.4, GPT-5.3-Codex, Spark
  3. Known Model Limitations
  4. Reasoning Effort Levels: none to ultra
  5. Model Verbosity and Summary Modes
  6. Cost vs. Capability Trade-Offs
  7. Per-Agent and Per-Task Model Selection

Chapter 15: Performance Optimization

  1. Understanding Your Token Budget
  2. Context Compaction: How It Works
  3. Reducing MCP Server Overhead
  4. File Exclusion Strategies with .codexignore
  5. Session Length Management
  6. Cost Estimation and Monitoring

Chapter 16: Troubleshooting and Common Pitfalls

  1. Authentication and Billing Errors
  2. Sandbox and Permission Failures
  3. Context Window Overflow
  4. MCP Server Timeouts and Connection Issues
  5. Installation and Environment Problems
  6. The Diagnostic Mindset: Systematic Debugging

Chapter 17: Real-World Workflows and Case Studies

  1. Solo Developer: Full-Stack Feature Implementation
  2. Team Workflow: Code Review Pipeline Integration
  3. CI/CD: Automated Testing and Bug Fixing
  4. Legacy Codebase Refactoring
  5. Documentation Generation and Maintenance
  6. Security Audit Workflows

Chapter 18: Migration Strategies – From Other Tools to Codex CLI

  1. Why Migrate? The Business Case
  2. Migrating from Claude Code
  3. Migrating from Cursor
  4. Migrating from GitHub Copilot
  5. Migrating from Aider
  6. Team Migration: Onboarding Without Disruption
  7. Credential and Provider Transitions
  8. When Not to Migrate

Chapter 19: Advanced Techniques and Future Directions

  1. Codex as an MCP Server for External Orchestration
  2. The OpenAI Agents SDK Integration
  3. Record and Replay: Building Skills from Sessions
  4. Plugins: Distributable Skill Bundles
  5. Hook Systems and Event-Driven Automation
  6. The Road Ahead: What to Watch For

Conclusion

References

Glossary

Index

Get the free sample chapters

Click the buttons to get the free sample in PDF or EPUB, or read the sample online here

The Leanpub 60 Day 100% Happiness Guarantee

Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

See full terms...

Earn $8 on a $10 Purchase, and $16 on a $20 Purchase

We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.

(Yes, some authors have already earned much more than that on Leanpub.)

In fact, authors have earned over $15 million writing, publishing and selling on Leanpub.

Learn more about writing on Leanpub

Free Updates. DRM Free.

If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).

Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.

Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.

Learn more about Leanpub's ebook formats and where to read them

Write and Publish on Leanpub

You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

Learn more about writing on Leanpub