Codex CLI: A Practical Guide to Terminal AI Coding

Codex CLI is OpenAI's open-source coding agent that runs entirely in your terminal, where you describe a task in plain language and it reads, edits, and runs code in your repo under approval and sandbox rules you control. You install the Codex CLI with one package command, sign in with a ChatGPT account or an API key, and from then on it works like a pair programmer that lives at the command line instead of an editor pane.

Most walkthroughs stop at "install it and type a prompt." That skips the two things that decide whether it saves you time: how you scope its permissions, and how you feed it accurate context without wasting tokens.

How do you install and set up the Codex CLI?

Two commands and a sign-in.

On macOS you install through npm or Homebrew:

npm install -g @openai/codex
# or
brew install codex

Then start it inside a project directory:

cd your-project
codex

On first run it asks you to authenticate. You can sign in with a ChatGPT account (Plus, Pro, and Team plans include Codex usage) or set an OPENAI_API_KEY. Configuration lives in ~/.codex/config.toml, where you set the model, the approval policy, and any MCP servers.

The config file is where the real setup happens. A minimal one looks like this:

model = "gpt-5-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Everything else is a default you can leave alone until you have a reason to change it. Start there, run a small task, and only then tune.

What can the Codex CLI actually do?

It reads your repo, plans, edits files, and runs commands, then stops at the boundaries you set.

The core loop: you type a request, it inspects the relevant files, proposes changes, and either applies them or asks first depending on your approval policy. It can run your test suite, read the failures, and iterate on its own fix. Because it runs in the terminal, it already has your shell, your environment variables, and your tooling in reach, so there is no separate integration to wire up.

Two settings shape its behavior more than anything else, and understanding them is the difference between a useful agent and a scary one.

Sandbox mode governs what it may touch. read-only lets it look but not write. workspace-write lets it edit inside the project directory but blocks network and changes outside the repo. A wider mode exists for when you fully trust the task. The sandbox is the blast radius, not the intent check.

Approval policy governs when it pauses to ask you. untrusted asks before nearly everything, on-request asks only when it wants to run something risky, and never runs unattended. Match the policy to the task, not to your impatience.

What are the most useful Codex CLI commands?

A handful of controls cover most sessions.

Inside a running session you steer with slash commands and flags rather than memorizing a manual. The most-used ones:

• codex "your task" runs a one-shot task non-interactively, useful in scripts and CI.
• codex --model <name> overrides the configured model for a single run.
• /approvals switches the approval policy mid-session when a task turns out riskier or safer than expected.
• /model swaps the model without restarting.
• /clear resets the conversation so a new task starts with a clean context window.
• @path/to/file pulls a specific file into context instead of letting it search.

A full reference of the Codex CLI commands is worth skimming once, because the difference between fighting the agent and steering it is usually one flag you did not know existed. The pattern to internalize: point it at the exact files, keep the context window tight, and review with git rather than trust.

Codex CLI vs the Codex app: which one do you need?

They share a model and differ in where they run. The difference between the Codex CLI and the Codex app comes down to environment and control.

The CLI wins when the work is on the machine in front of you and you want to watch every edit. The app wins when you want to hand off a well-scoped task and return to a pull request. Most developers run both and switch by the shape of the job, not out of loyalty to one.

How do you connect MCP servers to the Codex CLI?

You add them to config.toml under an [mcp_servers] block, and they appear as tools the agent can call.

The Model Context Protocol lets the Codex CLI talk to outside tools through a stable interface: a database, a browser, a screen-context server. A Codex CLI MCP setup is only a few lines:

[mcp_servers.pinvari]
command = "pinvari-mcp"
args = []

After that, the agent can call that server's tools mid-task. This is the cleanest way to give Codex abilities it does not ship with, and it is why MCP matters more than any single built-in feature. It is the extension point.

Where this gets useful for real product work is context. A coding agent in a terminal cannot see your screen. When you say "the spacing on this card is off," it has no idea which card, and asking it to guess from a pasted image is expensive and unreliable.

Why does the Codex CLI still edit the wrong UI element?

Because a terminal agent has no spatial sense of your app, so "this button" means nothing to it.

You describe a visual bug in words, the agent maps those words to the wrong component, and it confidently edits something you did not mean. The usual patch, pasting a screenshot, costs a pile of tokens per turn and still leaves the model guessing which of five similar buttons you meant.

This is the gap a point-and-speak layer closes. On macOS, every on-screen control is addressable through the Accessibility API: the element under any point exposes its role, label, and frame through AXUIElementCopyElementAtPosition. A tool that resolves that named element can hand the Codex CLI the exact control you circled instead of a picture to interpret.

PinVari does this and exposes it over MCP. You hold ⌥⌘A, circle the misaligned card, and say "tighten the padding on this to 8px." It resolves the named accessibility element on-device, transcribes your speech on-device, and queues a resolved instruction. Add it to your config.toml like any other MCP server and Codex pulls the element path, the spoken instruction, and a cropped screenshot through pinvari_next_instruction. The full mechanics are in the local MCP server for screen context write-up.

Because it resolves structure first, it also attaches a confidence score and marks whether you deliberately circled the target or your cursor merely dwelled over it. Below 0.8 confidence it asks rather than guesses. It runs on-device with no API keys of its own, and it is a one-time $39 launch license through Polar rather than a subscription, priced here.

FAQ

Is the Codex CLI free?

The CLI itself is open source and free to install. You pay for model usage, either through a ChatGPT plan that includes Codex or through your own OpenAI API key billed per token. There is no separate license for the tool.

Does the Codex CLI work on Windows and Linux?

It runs on macOS and Linux natively, and on Windows through WSL. The npm install command is the same across platforms, with Homebrew as an option on macOS.

What models can the Codex CLI use?

It defaults to OpenAI's Codex-tuned models and lets you switch in config.toml or with the --model flag. Which specific models you can reach depends on your ChatGPT plan or API access.

How is the Codex CLI different from Claude Code?

Both are terminal coding agents that support MCP servers. They differ in the underlying model, the exact approval and sandbox controls, and the surrounding ecosystem. Many developers keep both installed and pick per task, and the MCP tools you add work with either.

Can the Codex CLI see my screen?

Not on its own. It reads files and runs commands, not pixels. To give it what is on screen you add a screen-context MCP server, which is how a point-and-speak tool feeds it the exact UI element you pointed at rather than a screenshot it has to decode.