Codex CLI Complete Guide: From Setup to Automation

What Codex CLI Actually Does (And Why It's Different)

If you've used GitHub Copilot or wired GPT into your editor, you've probably noticed the same blind spots: cross-file refactoring, running tests automatically, self-correcting based on error output. These aren't things autocomplete handles well.

Codex CLI is built for exactly that gap. It's a coding agent that runs in your terminal — it reads and writes files, executes shell commands, iterates inside a sandbox, and keeps going until the task is done. This guide skips the theory and gets straight to usage.

---

Installation and Initial Setup

Codex CLI ships as an npm package. You need Node.js 18 or higher:

npm install -g @openai/codex
codex --version

After installation, set your API key. Codex reads it from the OPENAI_API_KEY environment variable — add it to ~/.zshrc or ~/.bashrc so it persists:

export OPENAI_API_KEY="sk-..."

The default model is GPT-5.4. Use the --model flag to switch:

codex --model gpt-5.5 "refactor the error handling across this project"
codex --model gpt-5.4-mini "add JSDoc comments to every function"

The model selection logic is straightforward: GPT-5.5 for complex architectural decisions, GPT-5.4 for everyday coding tasks, and mini for bulk documentation or repetitive work. Mini costs roughly one-eighth of the flagship model, so the tradeoff is worth knowing.

---

Sandbox Modes: The Core Safety Mechanism

The most important design decision in Codex CLI is its approval mode system — a tiered sandbox that controls what the agent can do without asking you first.

Mode	File Writes	Shell Commands	Network	Best For
suggest	Suggestions only	❌	❌	Code review, read-only inspection
auto-edit	✅ Automatic	Requires confirmation	❌	Day-to-day development
full-auto	✅ Automatic	✅ Automatic	Configurable	CI/CD, unattended scripts

For daily development, auto-edit is the right default. It writes files directly but pauses before running anything like npm test or git commit:

codex --approval-mode auto-edit "fix all TypeScript type errors"

In full-auto mode, Codex runs in a network-isolated sandbox with outbound connections blocked by default. If it needs to reach the npm registry, whitelist the host explicitly:

codex --approval-mode full-auto \
  --allowed-hosts registry.npmjs.org \
  "install dependencies and get the test suite passing"

In practice, full-auto on a mid-sized Node.js project — running the full cycle of install, test, fix failures, verify — typically takes four to six iterations. GPT-5.5 usually converges one or two rounds faster than GPT-5.4.

---

File Editing and Multi-Step Task Execution

Codex isn't a smarter autocomplete. It's an editing agent with persistent context. When it starts, it reads your current directory's file tree and injects git diff output into its context window. It understands what you're working on before it touches anything.

A typical multi-step workflow looks like this:

cd my-project
codex "migrate all REST routes from Express to Fastify, keeping the existing route signatures"

Codex will walk through the work sequentially: analyze existing route files → generate a migration plan → edit files one by one → update package.json dependencies → suggest which test command to run next. It logs every action as it goes. Hit Ctrl+C at any point to interrupt.

For long tasks that span multiple sessions, reload the previous session snapshot with --context:

codex --context .codex/session_abc123.json "continue the refactor — the auth module is still outstanding"

The .codex/ directory stores conversation history and a record of completed file operations, so you can pick up exactly where you left off.

One detail worth knowing: Codex only touches files tracked by git. Anything in .gitignore — including .env and node_modules — is off-limits by default. That's intentional. If you need it to work on untracked files, add --include-untracked.

---

Advanced Usage: Prompt Patterns and Custom Instructions

Writing prompts for Codex is different from prompting a chat model. You're issuing a task, not starting a conversation. A few patterns that consistently produce better results:

Constrain the scope. Specific instructions outperform vague ones every time. "Refactor error handling in src/api/routes.ts to use a centralized error class" will execute far more reliably than "improve code quality." Name the files, specify the stack, call out what must not change.

Use AGENTS.md for project-level instructions. Drop a file called AGENTS.md in your project root. Codex reads it automatically on every startup and treats it as standing system instructions. It's the right place for project conventions:

# Project Standards
- Use pnpm — not npm or yarn
- Test framework is Vitest, not Jest
- All async functions must have error boundaries
- Must pass `pnpm lint` before committing

This is worth the five minutes it takes to write. It's effectively 200 words of context injected into every session without you having to repeat yourself.

Pipe error output directly into Codex. The CLI accepts stdin, which makes it easy to feed test failures straight into the agent:

pnpm test 2>&1 | codex "fix the code based on these test failures"

You can do the same with code review comments:

cat review_comments.txt | codex --approval-mode auto-edit "apply these review suggestions"

---

How Codex Compares to Claude Code and Gemini CLI

Codex's direct competition is Anthropic's Claude Code and Google's Gemini CLI. Each has a distinct strength.

Claude Code has an edge on long-context coherence and multi-file consistency — Claude Opus 4.8 carries a larger context window, which matters on big refactors. Gemini CLI integrates most naturally with Google Workspace tooling. Codex's strengths are its native integration with the OpenAI ecosystem and GPT-5.5's benchmark performance on code generation tasks.

The good news is that the API interfaces are close enough that switching between them in the same project is low-friction. An OpenAI-compatible proxy lets you run all three against the same codebase and compare results without changing your workflow.

---

The Real Value Proposition

After using Codex CLI for a while, the thing that stands out isn't raw generation speed. It's the ability to automate the full feedback loop: write code → run tests → read errors → apply fixes → verify again. That loop, fully unattended, is where the productivity gains actually compound.

If you're running Codex CLI alongside Claude Code or Gemini CLI for comparison — or want to run GPT-5.5 at significantly lower cost — I'd point you toward XycAi (https://www.xyc.ai). It's an OpenAI-compatible API aggregating 200+ models under one endpoint, with GPT and Claude official models starting at 14% of list price. Native support for Codex CLI, Claude Code, and Gemini CLI means switching between agents is a single environment variable change — nothing else in your workflow needs to touch.