OpenAI Codex CLI: The Complete Setup & Commands Guide

If you've ever wished your terminal could just understand what you want and write the code for you — that's exactly what the OpenAI Codex CLI does.

It's a coding agent that lives in your terminal. You type a task in plain English, and it reads your project, writes code, runs commands, and fixes its own mistakes. No tab-switching. No copy-pasting. Just you and your command line.

This guide covers everything: how to install it, how to log in, the commands you'll actually use, and the mistakes to avoid. Let's get you set up.

What is the OpenAI Codex CLI?

The Codex CLI is OpenAI's terminal-based coding agent. Built in Rust, it reads your codebase, edits files, runs commands, and manages git workflows from the command line.

The best part about it for safety: Codex runs with OS-native sandboxing — Seatbelt on macOS and Bubblewrap on Linux — so it can safely execute commands without risking your system.

In simple words, the CLI gives you a real AI engineer inside your terminal, and it can't accidentally wreck your machine while doing its job.

Read Now: Codex Cannot Access Its Local Database — How to Fix It

What You Need Before Installing

Two quick things:

1. Node.js 18 or higher (Node 22 is recommended in 2026). If you don't have it, install it first.
2. A ChatGPT account (Plus, Pro, Business, or Enterprise) — OR an OpenAI API key if you prefer pay-per-use billing.

That's it. If you already pay for ChatGPT, you don't need an API key at all. Codex usage rides on top of your subscription up to your tier's monthly limit, and this is the official recommendation for individual developers.

How to Install OpenAI Codex CLI

Here's the part most people get wrong, so read carefully.

The One Command

bash

npm install -g @openai/codex

Then verify it worked:

bash

codex --version

The #1 Install Mistake

The most common Codex CLI install failure is running npm i -g codex instead of npm i -g @openai/codex. The unscoped "codex" package is an unrelated 2012 project with no connection to OpenAI — it installs silently and then does nothing useful.

So always include the @openai/ part. This one typo wastes more time than any other issue.

Other Install Methods

If npm isn't your style:

bash

# macOS (Homebrew)
brew install --cask codex

# Verify
codex --version

One heads-up: if brew install --cask codex installs the desktop app instead of the CLI, use the npm path for the CLI specifically.

On Windows

The recommended native Windows path in 2026 is PowerShell with npm. Install Node.js 22 first (use nvm-windows or a direct download), then run the same npm install -g @openai/codex command. Codex CLI on native Windows uses an AppContainer-based sandbox that restricts filesystem writes and limits network access by default, though OpenAI still labels Windows sandbox support as experimental.

Read Now: OpenAI Codex Just Replaced My Junior Developer (Here's How)

How to Log In

After installing, just run:

bash

codex

The first time, it opens your browser for a ChatGPT login. Sign in, and you're done — no API key needed.

If you'd rather use an API key (for CI pipelines or precise billing):

bash

export OPENAI_API_KEY="your-key-here"
codex

The CLI also reads OPENAI_API_KEY from ~/.codex/config.toml if you prefer not to put secrets in your shell environment.

Your First Task

Here's the magic moment. Open any project folder in your terminal and run:

bash

codex

Then just type what you want in plain English:

"Find all unused imports in this project and remove them."

Or run a task directly in one line:

bash

codex --full-auto "Run tests and fix any failures"

Codex will read your code, make a plan, do the work, and show you what it changed. You approve or reject. Simple.

The Three Safety Modes (Important)

This is the most important thing to understand about the CLI. Codex has three permission levels that control how much freedom it has:

Mode	What It Does	When to Use
Read Only	Codex can read your files but not change anything	Exploring a new codebase safely
Auto	Codex can edit files and run safe commands, asks before risky ones	Daily work (the default sweet spot)
Full Access	Codex can do anything, including network and system commands	Only when you fully trust the task

These modes matter because LLMs can hallucinate and delete files, install vulnerable packages, or edit system files — so always review agent actions. You can take more risks inside sandboxes.

A smart tip: instead of reaching for full access, use the --add-dir flag to grant access to specific directories only.

Useful Commands & Shortcuts

Once you're inside a Codex session, type / to see available commands. Here are the ones you'll use most:

• /model — switch the AI model mid-session
• /mcp — list connected Model Context Protocol tools
• codex exec — run a task non-interactively (great for scripts)
• --full-auto — let Codex work without stopping for approvals
• --add-dir — give Codex access to specific folders
• codex --version — check your installed version

The Config File Nobody Tells You About

Here's what separates beginners from power users: the config file.

The real surface area of Codex CLI is ~/.codex/config.toml — model selection, three approval modes, three sandbox levels, MCP servers, and a per-project AGENTS.md that quietly shapes every prompt.

Codex looks for ~/.codex/config.toml on every run. If it's absent, it uses defaults.

You can also connect external tools through MCP servers. Configure them in config.toml under an [mcp_servers.name] section with a command, environment variables, and a timeout, then list connected tools in-session with /mcp.

For project-specific instructions, create an AGENTS.md file in your repo. Codex reads it automatically and follows your rules on every task — like a permanent set of guidelines for that project.

Read Now: GPT-5.1: Everything You Need to Know

Common Problems & Fixes

Most Codex CLI issues fall into four categories: approval prompts that won't stop, network access denied, sandbox errors on WSL/macOS, and authentication loops.

Here are quick fixes:

"codex: command not found" after install Your PATH doesn't include npm's global bin directory. Run npm bin -g to find the path, then add it to your shell profile.

Approval prompts won't stop Switch to --full-auto mode, or adjust your approval settings in config.toml.

Network access denied The sandbox blocks network by default. Grant access through config or use a less restrictive mode for that task.

Authentication loops Log out and back in. If using an API key, double-check it's valid and has credits.

How Much Does Codex CLI Cost?

The CLI itself is free. You pay through your ChatGPT plan or API usage:

• ChatGPT Plus ($20/month) — usage included, great for starting out
• ChatGPT Pro ($200/month) — much higher limits for heavy users
• API key — pay per token. New accounts get $5 in free credits, and you can check usage at platform.openai.com.

If you already pay for ChatGPT, the CLI costs you nothing extra until you hit your monthly limit.

Codex CLI vs ChatGPT — What's the Difference?

People mix these up all the time. Simple answer:

Codex CLI is a terminal-based AI coding assistant that can read your codebase, execute commands, and modify files. ChatGPT is a web interface for general conversation. Codex CLI is designed specifically for software development workflows.

ChatGPT talks about code. Codex CLI writes and runs it.

Conclusion

The OpenAI Codex CLI turns your terminal into a coding partner. Install it with one command, log in with your ChatGPT account, and start giving it tasks in plain English.

Start in Auto mode, always review what it does, and explore the config.toml file once you're comfortable. Within a week, you'll wonder how you ever coded without it.

The future of the command line isn't memorizing commands. It's just telling your terminal what you want.

FAQs