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, rewritten in Rust as of early 2026. 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. The recommended model is GPT-5.5 (other options include GPT-5.5-mini for faster/cheaper tasks and the Codex-tuned variants); use /model to see the current default and switch.

Key features:

• Autonomous multi-step task execution
• Can work with git workflows (including branches) when used inside a git repository
• Sandboxed execution for safety
• Voice input (hold spacebar to dictate), web search, and MCP server support
• Session resume (codex resume) to pick up where you left off
• codex exec for non-interactive scripting and CI pipelines
• Subagents for parallel task execution
• Open source (Rust)

Installation

Step 1: Install Codex CLI

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

npm install -g @openai/codex

Option B — Homebrew (macOS):

brew install --cask codex

Option C — Pre-built binary (no Node.js needed):

Download the latest binary for your platform from the Codex CLI releases page and add it to your PATH.

Verify (any install method):

codex --version

Step 2: Sign in

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

codex

On first launch, Codex will open a device-code sign-in flow in your browser. Sign in with your ChatGPT account and you’re done. This works with any ChatGPT plan (Plus, Pro, Business).

export OPENAI_API_KEY="your-key-here"

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 permission profile, Codex will ask for your approval before each step. Type y to approve or n to reject. Use /mode (or the equivalent permission-profile command — see /help) to switch autonomy levels, 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):

The legacy --full-auto flag is being phased out in favor of explicit permission profiles that combine an approval policy and a sandbox policy. Run codex --help or /help inside a session to see the current profile names — the names have shifted across releases, so prefer reading them from the tool 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 /mode (or current profile-switch 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.

Voice input

Hold the spacebar to dictate your prompt instead of typing. Useful for describing complex tasks conversationally.

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.

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 "What is 2 + 2? Reply with just the number."

Key Takeaways

• Multiple install options — npm install -g @openai/codex, brew install --cask codex, or download a pre-built binary
• Sign in with ChatGPT — device-code flow is the easiest auth; API key still works for CI/scripting
• Two policy axes — approval policy controls when Codex asks permission, sandbox policy controls what it can access
• 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 — Suggest mode shows you how an AI approaches a problem step by step