Codex CLI

By the end of this lesson, you’ll have Codex CLI installed and understand its unique strength: the ability to plan, execute, and iterate on tasks with minimal hand-holding.

What is Codex CLI?

Codex CLI is OpenAI’s open-source command-line coding agent, written in Rust. It’s designed for autonomous task execution — you assign it a task, and it can plan, implement, test, and iterate with minimal guidance, but outputs still require human review. OpenAI lists GPT-5.6 Sol as its flagship tier; Terra is the balanced, cheaper sibling — and the only model on Free and Go — and Luna the fastest. Use /model to see what your plan offers and to pick both the model and its reasoning effort. (GPT-5.4 and GPT-5.4 mini are retired from Codex for ChatGPT sign-ins as of August 31, 2026, replaced by gpt-5.6-terra and gpt-5.6-luna in saved configs, custom agents, and scheduled tasks — if you authenticate with your own API key instead, this deprecation doesn’t apply to you.)

Key features:

• Autonomous multi-step task execution
• Can work with git workflows (including branches) when used inside a git repository
• Sandboxed execution for safety
• Web search (--search), MCP servers, plugins, and skills
• Session resume (codex resume) to pick up where you left off
• codex exec for non-interactive scripting and CI pipelines
• Subagents for parallel work — the ultra reasoning setting fans a task out to four of them
• /import pulls your settings and MCP servers over from Claude Code or Cursor
• Open source (Rust)

Installation

Step 1: Install Codex CLI

Option A — Installer script (recommended; no Node.js needed):

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On Windows native (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Option B — npm (if you already have Node.js):

npm install -g @openai/codex

Option C — Homebrew (macOS):

brew install --cask codex

Verify (any install method):

codex --version

Later, codex update upgrades in place and codex doctor diagnoses install, config, and auth problems.

Step 2: Sign in

The easiest way to authenticate is with your ChatGPT account — no API key needed:

codex

On first launch, Codex opens a browser sign-in. Sign in with your ChatGPT account and you’re done. This works with every ChatGPT plan, including Free and Go (with tighter limits and the Terra model only).

On a remote server over SSH, use the device-code flow instead — it prints a URL and a code you enter on any browser:

codex login --device-auth

export OPENAI_API_KEY="your-key-here"
printenv OPENAI_API_KEY | codex login --with-api-key

echo 'export OPENAI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

Your first interaction

Step 1: Create a project folder

mkdir hello-codex && cd hello-codex

Step 2: Start Codex CLI

codex

Step 3: Give it a task

Create a simple to-do list app in a single HTML file. It should:
- Let users type a task and press Enter to add it
- Show tasks in a list with checkboxes to mark as done
- Have a "Clear completed" button
- Dark theme, clean design
- Save tasks to localStorage so they persist on refresh

Codex will:

1. Plan the implementation
2. Create the file
3. Write the code
4. Verify it meets requirements

In the most cautious setting, Codex will ask for your approval before each step. Type y to approve or n to reject. Use /permissions to switch autonomy levels (see /help), or Ctrl+C to quit.

Step 4: Check the result

ls
cat index.html

Open in your browser to test the todo list functionality.

Codex CLI modes

Codex CLI controls autonomy through two independent policies — approval (when it asks permission) and sandbox (what it can access):

Combine them on the command line — codex -a on-request -s workspace-write is the everyday setting — or switch mid-session with /permissions, which offers named permission profiles (read-only, workspace, full access). The old --full-auto shortcut is now a deprecated compatibility flag on codex exec — it still runs but prints a warning; substitute --sandbox workspace-write instead. Names shift between releases, so prefer reading them from /help over memorizing.

Start with the most cautious profile while learning, then open up autonomy as you get comfortable. Full autonomy is best reserved for low-stakes prototypes where you can easily discard the results.

Tips

1. Be specific about requirements. Codex excels when you give it a clear, well-defined task. The more specific your instructions, the better the result.

2. Start with small tasks. Build confidence with simple, single-file tasks before trying multi-file projects.

3. Use the sandbox. Codex runs in a sandboxed environment that reduces blast radius. It is not a substitute for review — read the diff before accepting changes, especially on important projects.

4. Review before accepting. In the cautious permission profile, Codex shows you what it wants to do before doing it. Use this to learn what good code looks like.

Power features

Mid-session mode switching

You do not have to restart Codex to change permission profiles. Use the in-session /permissions command (see /help) to step up or down autonomy. This lets you start careful and open up autonomy as you gain confidence in the task.

Sandbox

By default, Codex CLI uses a restricted execution environment controlled by the sandbox policy. The workspace-write default limits changes to your project directory. Network and file permissions depend on your configuration and OS. The sandbox reduces blast radius, but it does not replace review — verify the behavior in your environment before relying on it for safety-critical work, and always read the diff before accepting changes.

Reasoning effort and fast mode

/model sets both the model and how hard it thinks: low → medium → high → xhigh → max, plus ultra on Astra, Sol, and Terra, which adds automatic delegation to parallel subagents (and burns through your window faster — Codex warns you). Sol is strong even at low effort, so start low and raise it for hard problems. /fast trades extra usage for faster responses.

Session resume

Run codex resume to pick up a prior session where you left off — handy if you get interrupted or want to continue a multi-step task later. /new starts a fresh thread and lets you name it.

Headless runs

codex exec "your prompt" runs one task non-interactively and exits — the building block for scripts and CI. Add --json for machine-readable events or -o result.md to save the final message. You’ll use this in Module 19, where agents run headless in CI.

Verify it works

Paste this exact command to confirm everything is set up correctly:

codex --version

You should see a version number printed. If you get “command not found,” revisit the installation step above.

codex exec "What is 2 + 2? Reply with just the number."

Key Takeaways

• Multiple install options — the installer script (curl -fsSL https://chatgpt.com/codex/install.sh | sh), npm install -g @openai/codex, or brew install --cask codex
• Sign in with ChatGPT — any plan works, even Free; codex login --device-auth for SSH; API key still works for CI/scripting
• Two policy axes — approval policy controls when Codex asks permission, sandbox policy controls what it can access (--full-auto is deprecated in favor of --sandbox workspace-write)
• The sandbox reduces blast radius — Codex runs in isolation, but you still review the diff before accepting
• Specificity wins — the more precise your task description, the better the result
• Review is learning — the read-only profile shows you how an AI approaches a problem step by step