Codex CLI Docs: Complete Command Reference & MCP Use

The Codex CLI is a local command-line coding agent that accepts plain-English instructions, plans changes, and writes code directly in your project without sending anything to a remote API. You install it once (brew install codex-cli), point it at a directory, and ask it to refactor a function or add a feature — it edits files, runs tests, and loops until the task is done. Most devs hit the docs looking for two things: the full command set (what codex can actually do from a shell) and how to connect an MCP server so the agent can read your screen or hit a local database mid-task without you copy-pasting context manually.

The confusion stems from Codex shipping both a CLI (codex) and a GUI app (Codex.app) — same agent core, different interfaces. The CLI lives in your terminal and orchestrates file edits via LLM calls; the app wraps the same engine in a chat window with buttons. The real power comes from Model Context Protocol (MCP) servers: small local binaries the agent calls when it needs data beyond the file tree. Connect PinVari's MCP server and Codex can request a screen capture mid-task, resolve the exact UI element you circled, and write the fix — all on-device, no API key upload.

What commands does the Codex CLI expose?

The core set (as of January 2026):

The Codex CLI vs Codex app split: the CLI is faster for batched edits across many files (shell scripting, CI hooks); the app is nicer for exploratory debugging where you want a persistent chat history and inline diffs. Both share the same ~/.codex/mcp/ config and call the same MCP servers.

Run codex --help for flags (--model, --context-window, --dry-run to preview the plan without writing files). The agent defaults to on-device inference if you have an M-series Mac with ≥16 GB unified memory; otherwise it falls back to Anthropic's API (you set ANTHROPIC_API_KEY in ~/.codex/config.json or the app handles the key prompt). No telemetry is sent unless you enable crash reports in settings.

How do I connect an MCP server to Codex CLI?

An MCP server is a small program that exposes tools the agent can call. It runs locally, speaks JSON-RPC over stdio, and dies when Codex closes. The protocol is open (modelcontextprotocol.io); anyone can write one.

Step-by-step for macOS:

1. Get a connector binary. Example: PinVari installs ~/.pinvari/mcp/pinvari-mcp when you click Connect → Codex inside the app. Alternatively download a prebuilt connector (e.g., filesystem-mcp, postgres-mcp) or write your own in Python/Node and wrap it in a shell script that starts the server.

1. Register it: codex mcp add pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp". The -- separates the server name from the path; Codex spawns the binary and pipes stdio. Check it worked: codex mcp list → you see pinvari with status running.

1. Use it in an instruction: codex "fix the button I circled". Mid-task the agent realizes it needs a screenshot, calls pinvari_request_capture, PinVari's notch island lights up prompting you to circle something, you draw a region, the capture flows back to Codex with the named accessibility element (role: AXButton, title: "Submit", frame: {x:120, y:340, w:80, h:32}), and the agent writes the fix targeting that exact element.

1. Verify the tool schema: codex mcp list --verbose dumps each server's exposed tools and their arguments. PinVari exposes pinvari_request_capture (no args, blocks until you finish marking) and pinvari_next_instruction (fetches queued captures without blocking).

If a server crashes Codex logs the error to ~/.codex/logs/mcp-<name>.log and marks it stopped. Run codex mcp reload to restart all servers.

What does PinVari's MCP server actually send to Codex?

When the agent calls pinvari_request_capture:

1. PinVari's overlay activates (the lime freehand canvas appears on top of all windows).
2. You circle or point at a UI element and optionally speak an instruction (or just press ⏎ to finish silently).
3. PinVari resolves the macOS accessibility element under the circled region via AXUIElementCopyElementAtPosition → you get role, title, value, frame, and parent hierarchy. If the element has no label (e.g., a bare AXGroup), PinVari descends to the deepest labeled child. Chromium apps get AXDOMIdentifier and AXDOMClassList as fallback names. If AX is blind (canvas, some games) PinVari runs on-device Vision OCR and returns recognized text plus bounding boxes.
4. The JSON payload flows back to Codex:

{
  "element": {
    "role": "AXButton",
    "title": "Add to Cart",
    "value": null,
    "frame": {"x": 420, "y": 680, "w": 120, "h": 44},
    "parent_chain": ["AXWindow", "AXGroup", "AXScrollArea", "AXButton"],
    "dom_id": "checkout-btn",
    "confidence": 0.94,
    "provenance": "circled"
  },
  "instruction": "make this button blue",
  "screenshot_base64": "<cropped-png>",
  "timestamp": 1724371200
}

The agent now knows the exact named element (not a pixel guess), sees what it looks like, and has your spoken instruction. It writes the CSS/SwiftUI/Electron code targeting #checkout-btn or the AX title. No ambiguity.

Compare that to pasting a full-window screenshot and typing "the button on the right" — the agent guesses. PinVari's AX resolution removes the guesswork and lets Codex write surgical fixes. Read Can Claude Code see my screen? for how other agents handle screenshots (spoiler: most don't resolve named elements).

Codex CLI MCP vs manual context pasting

The MCP path wins on speed and ergonomics: the agent requests, you point, the capture flows back automatically. No clipboard juggling. The accessibility tree gives ground truth but exporting it manually breaks flow. PinVari automates the export and crops to what you circled.

For agentic coding where the agent loops (fix → test → refine), shaving 15 seconds per iteration compounds fast. A 10-iteration debug session saves 2.5 minutes of copy-paste overhead.

Common Codex CLI commands developers actually use

Start a task in the current directory:

codex "refactor auth.js to use async/await"

Dry-run to preview the plan without writing files:

codex --dry-run "add error handling to the API client"

Use a specific model (if you have multiple configured):

codex --model claude-3-5-sonnet "optimize the database query in users.py"

Connect PinVari's MCP server (one-time setup):

codex mcp add pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"

List all MCP servers:

codex mcp list

Remove a server:

codex mcp remove pinvari

Reload all servers after updating a connector:

codex mcp reload

Check version:

codex version

The agent works best with concrete instructions scoped to one file or module. Vague asks ("improve the app") produce vague plans. Specific wins: "add input validation to the signup form in components/SignupForm.tsx" → the agent edits one file, writes a test, and exits.

When should I use Codex CLI vs the Codex app?

Use the CLI when:

• You're already in a terminal and want one-shot edits (shell scripts, CI hooks, batch refactors).
• You're automating tasks: for f in src/*.js; do codex "add JSDoc to $f"; done.
• You want stateless runs (each invocation is independent; no chat history bloat).

Use the app when:

• You're debugging interactively and want multi-turn chat with inline diffs.
• You prefer clicking buttons over typing commands.
• You want persistent history across sessions.

Both interfaces call the same agent core and MCP servers. The app is just a GUI wrapper around the CLI's engine. Some devs run both: CLI for scripted edits, app for exploratory work. See Claude Code vs Codex for how Anthropic's competing agent differs (cloud-first, no local MCP by default).

For AI coding agents generally, the trend is local-first execution with remote fallback. Codex nails this: on-device inference if your Mac can handle it, API call if not, but either way the MCP servers run locally and nothing uploads unless you use a cloud model.

How PinVari makes Codex (or any MCP-compatible agent) faster

The problem: coding agents need context. When you say "fix this button", the agent doesn't know which button or what's wrong. You screenshot, describe, maybe paste DOM — takes 15–30 seconds, breaks flow.

PinVari's solve: hold ⌥⌘A, circle the button, say "make it blue", release. PinVari screenshots, transcribes on-device, resolves the macOS accessibility element under your circle (role: AXButton, title: "Submit", frame: {x, y, w, h}), and — if you have the MCP server connected — pushes the resolved element + cropped screenshot + your words to Codex automatically. The agent gets a named, executable instruction in ~2 seconds. No clipboard, no typing, no ambiguity.

Because PinVari reads the real accessibility tree (not pixel-guessing), the agent writes code targeting the exact element. Circle a SwiftUI Button → Codex writes .foregroundColor(.blue) on the right view. Circle an Electron checkbox → it targets the CSS class or data-testid. If the app is AX-blind (canvas, games), PinVari falls back to on-device OCR and returns text bounding boxes — still better than "somewhere in the middle".

The MCP connector lives at ~/.pinvari/mcp/pinvari-mcp after you install PinVari and click Connect → Codex inside the app. One-click install (or run codex mcp add pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp" manually). Full setup in Codex CLI. The app must be running for the connector to work (it talks to PinVari on 127.0.0.1:3402).

Price: $39 launch (first 500 licenses, then $59), one-time via Polar. No subscription for the core app. Team seats available at /#pricing. Faster than screenshots + descriptions, honest about AX limits (canvas/games fall back to OCR), and on-device by default — no API key upload unless you choose a cloud model.

FAQ

What's the difference between codex and codex mcp add?

codex runs the coding agent on an instruction. codex mcp add registers a local MCP server so the agent can call its tools mid-task. Example: codex mcp add pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp" tells Codex "when you need a screenshot or UI element, call this binary." After registration you just run codex "fix the dialog" and the agent autonomously calls pinvari_request_capture if it decides it needs a screen capture.

Can I use Codex CLI without any MCP servers?

Yes. The CLI works standalone — it reads your directory, plans edits, writes files. MCP servers are optional extensions that give the agent superpowers (screenshot capture, database queries, API hits). Without them the agent only sees the file tree and whatever you paste in the instruction. Most devs start with zero MCP servers and add them when they hit a repetitive task (e.g., "I keep pasting screenshots manually").

Does Codex CLI send my code to Anthropic or OpenAI?

Only if you configure a cloud model. On an M-series Mac with ≥16 GB RAM, Codex defaults to on-device inference (nothing uploaded). If you set --model gpt-4 or claude-3-5-sonnet, the agent sends the file context and instruction to that API. MCP servers (like PinVari's) run locally and talk to Codex over stdio — screenshots and resolved UI elements never leave your machine unless the LLM itself is cloud-hosted. Check codex config get model to see which model you're using.

How do I see what an MCP server exposes before connecting it?

Most connectors ship a --list-tools flag or a JSON schema file. PinVari's connector logs its schema to ~/.pinvari/mcp/schema.json on first run. After connecting, run codex mcp list --verbose to dump each server's tools and arguments. Example output: pinvari_request_capture (no args, blocking) → returns {element, instruction, screenshot_base64}. If a server's docs are unclear, connect it in dry-run mode (codex --dry-run "test task") and watch the logs in ~/.codex/logs/mcp-<name>.log.

Can I write my own MCP server for Codex?

Yes. The Model Context Protocol is open (spec at modelcontextprotocol.io). Write a program in any language that reads JSON-RPC from stdin, calls your local tool (database, API, file scanner), and writes the result to stdout. Wrap it in a shell script, register with codex mcp add myserver -- /path/to/script.sh, and Codex will spawn it and call exposed tools. PinVari's connector is ~300 lines of Swift hitting the Accessibility API; you could write a Postgres connector in Python in an afternoon. See best screenshot MCP servers for examples.

What happens if an MCP server crashes mid-task?

Codex logs the error to ~/.codex/logs/mcp-<name>.log, marks the server stopped, and continues the task without that tool. The agent might say "I can't capture the screen because the MCP server failed" and ask you to paste a screenshot manually. Run codex mcp reload to restart all servers, or codex mcp remove <name> if the connector is broken. Most crashes come from missing dependencies (e.g., a Python server without the venv activated) or permission errors (the connector can't read ~/.codex/). Check the log for the stack trace.