Codex CLI changes fast enough that half the tutorials you find describe flags that no longer exist. This guide was written with the CLI open: every command below was checked against codex --help on version 0.166.0, and every vendor fact was read from OpenAI's documentation on November 18, 2026.

The short version
  • Install is one line: a standalone script, npm or Homebrew. codex update keeps it current and codex doctor diagnoses a broken install.
  • Sign in with a ChatGPT plan or an API key. The plan route unlocks cloud features; the key route bills per use.
  • Codex runs in a sandbox by default. It can edit inside the workspace and asks before going further. That default is the main thing to understand.
  • "Auto mode" is really "Approve for me". A reviewer agent answers approval requests for you. --full-auto is gone.
  • AGENTS.md carries your project rules; ~/.codex/config.toml carries your settings, MCP servers and plugins.
  • Our honesty note: the studio uses Codex CLI lightly, alongside Claude Code as the daily tool. This is a verified setup guide, not a veteran's memoir.

What Codex CLI is, and how much we use it

OpenAI's README describes Codex CLI as "a coding agent from OpenAI that runs locally on your computer". You run it in a project folder, describe a task, and it reads files, edits them and runs commands, pausing for approval when it needs to step outside its sandbox. The CLI is open source under the Apache 2.0 licence. It's one of several Codex surfaces: there's also a desktop app, an IDE extension, a web and cloud version, and mobile access.

Our position, stated plainly: Rough Works uses Codex CLI lightly. Claude Code is the tool we work in all day; the Codex prompt history on our main machine holds about 130 entries against a little over four thousand for Claude Code. So where this guide says "we", it means "we ran this command and read this file", not "we have shipped fifty projects with it". For the head-to-head, see Claude Code vs Codex, and for the wider picture of what these tools are, AI agents explained.

That limit has one advantage. A guide built from the tool's own help output and today's documentation can't drift into habits from an older version.

Codex CLI install, update and sign-in

Pick one install route. These are from OpenAI's README as of November 2026.

# macOS and Linux: standalone installer
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# or a package manager
npm install -g @openai/codex
brew install --cask codex
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Then confirm it and start it:

codex --version      # prints: codex-cli 0.166.0 on our machine
cd your-project
codex

Windows. OpenAI's Windows documentation says Codex runs natively on Windows through the desktop app, the CLI and the IDE extension, and that the native sandbox means you don't need WSL or a virtual machine. Windows 11 is the recommended baseline; Windows 10 (version 1809 or later) is "best effort". WSL is still an option if you need Linux-native tooling. Documentation only on this point: we run Codex on macOS.

Updating. The CLI has its own command:

codex update

Its help text reads "Update Codex to the latest version", and the CLI reference adds that it applies an update "when the installed release supports self-update". If you installed through npm or Homebrew, upgrading through the same package manager is the safe route. OpenAI's CLI page also lists re-running the install script as the update step.

When something is off. Run the diagnostic before you search for an error message:

codex doctor            # install, config, auth and runtime checks
codex doctor --summary  # grouped rows and a final count

Sign in: ChatGPT plan, API key or device code

The first time you run codex, it asks how you want to sign in. The authentication docs describe the options, and each maps to a flag we confirmed in codex login --help.

codex login                 # browser flow, the default
codex login --device-auth   # device code, for machines with no browser
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status          # which method is active
codex logout

Which one you choose decides how you're billed and what works:

  • Sign in with ChatGPT uses your plan's allowance. As of November 2026, OpenAI's pricing page says Codex is included in every ChatGPT plan, each with its own usage limits. This route is required for Codex Cloud.
  • API key bills at API rates and doesn't draw on a plan. The docs say features that depend on a ChatGPT workspace or cloud services are "limited or unavailable" this way, and some plugins won't connect because their sign-in needs OAuth.
  • Device code is the fix for remote and headless hosts where the browser callback can't reach localhost. The docs call it beta and say you may need to enable it in your ChatGPT security settings first.

Credentials are stored according to the cli_auth_credentials_store setting: a file under ~/.codex, the operating system's keyring, or auto. If yours is the file, treat it like a password. We never open it, and it should never be committed or pasted into a prompt.

First run and the Codex CLI commands worth knowing

Inside the terminal UI, a handful of slash commands cover most of a session. OpenAI's CLI page highlights these:

  • /init generates an AGENTS.md scaffold for the project.
  • /status shows the session, context usage and rate limits.
  • /permissions switches permission mode.
  • /model picks the model.
  • /review starts a code review of your changes.
  • /mcp shows connected MCP servers.

A sensible first session:

  1. cd into a Git repository. Codex expects one, and Git gives you a way back. OpenAI recommends creating checkpoints before and after a task so you can revert.
  2. Run codex and type /init. Read the AGENTS.md it drafts and cut anything that isn't true.
  3. Ask a read-only question first: "Explain how the build works and where the tests live."
  4. Give it a small, checkable change. Approve or decline what it asks for.
  5. Run /review before you commit.

Outside the UI, these are the subcommands from codex --help that earn a place in memory:

Command What it does
codex "prompt" Start an interactive session with an opening prompt
codex exec "prompt" Run non-interactively and print the final message
codex review --uncommitted Review staged, unstaged and untracked changes
codex review --base main Review a branch against a base branch
codex resume --last Continue the most recent session
codex fork --last Branch a previous session into a new one
codex mcp list Show configured MCP servers
codex plugin list Show available plugins
codex features list Show feature flags and their stage
codex completion Generate shell completion scripts
zsh · codex-cli 0.166.0$ codex --versioncodex-cli 0.166.0$ codex --helpUsage: codex [OPTIONS] [PROMPT] codex [OPTIONS] <COMMAND> [ARGS]Commands: exec Run Codex non-interactively [aliases: e] review Run a code review non-interactively login Manage login logout Remove stored authentication credentials mcp Manage external MCP servers for Codex plugin Manage Codex plugins completion Generate shell completion scripts update Update Codex to the latest version doctor Diagnose local Codex installation, config, auth, and runtime health sandbox Run commands within a Codex-provided sandbox resume Resume a previous interactive session (picker by default; use --last to continue the most recent) fork Fork a previous interactive session (picker by default; use --last to fork the most recent) cloud [EXPERIMENTAL] Browse tasks from Codex Cloud and apply changes locally features Inspect feature flags# (excerpt: the full list on 0.166.0 has 28 commands, including help)
Real output from codex --help on our machine, 18 November 2026 (excerpt).

Useful global flags, also from the help output: -m to choose a model, -C <dir> to set the working root, --add-dir <dir> to make another directory writable, -i <file> to attach an image, --search for live web search, and --worktree to run the session in a new managed Git worktree.

Approval and sandbox modes, and what "auto mode" means

This is the part of Codex worth understanding before anything else, because it decides what the agent can do while you're not looking.

Two separate controls are in play. OpenAI's sandbox documentation puts it this way: the sandbox defines what's technically possible, and approvals decide when the agent pauses.

The sandbox has three modes, set with -s or --sandbox:

  • read-only: inspect files; no edits or commands without approval.
  • workspace-write: read, edit inside the workspace and run routine local commands there. This is the default for local work.
  • danger-full-access: no filesystem or network boundary at all.

It's enforced by the operating system (Seatbelt on macOS, bubblewrap on Linux and WSL2, a native sandbox on Windows) and applies to everything the agent spawns: git, package managers, test runners.

The approval policy, set with -a or --ask-for-approval, has two values in today's CLI: on-request (work inside the sandbox, ask to go beyond it) and never. The docs note the older untrusted value is retired.

On top of those, the permission modes page names four modes you choose with /permissions:

Mode Sandbox Who answers approval requests
Ask for approval workspace-write You
Approve for me workspace-write An automatic reviewer
Full access none Nobody; nothing asks
Custom (config.toml) whatever you configured whatever you configured

So what is "Codex CLI auto mode"? There is no mode with that exact name in the documentation as of November 2026. What people mean is Approve for me. OpenAI's auto-review page explains it: eligible approval requests go to a separate reviewer agent, which approves or denies with a rationale. It's designed to block things like sending secrets to untrusted destinations, probing for credentials and destructive actions. The sandbox boundary doesn't change. From the command line:

codex --approve-for-me

Or permanently, in config.toml:

approval_policy = "on-request"
approvals_reviewer = "auto_review"
sandbox_mode = "workspace-write"

Three cautions, all from OpenAI's own pages:

  • Auto-review "is not a deterministic security guarantee". It reviews only the requests that needed approval in the first place.
  • --full-auto is no longer supported. If an old script uses it, switch to --sandbox workspace-write or --approve-for-me.
  • --dangerously-bypass-approvals-and-sandbox exists, and its help text says it is "intended solely for running in environments that are externally sandboxed". Believe it.

Our advice from supervising agents every day in a different tool: start in Ask for approval for a week. The prompts teach you what the agent actually reaches for. Move to Approve for me once those prompts have become predictable.

AGENTS.md and config.toml: instructions and settings

AGENTS.md: your project's standing instructions

Codex reads a file called AGENTS.md before it does any work. It's plain Markdown: build commands, test commands, conventions, things never to touch. /init drafts one for you.

OpenAI's AGENTS.md guide documents exactly how files are found:

  1. Global. In ~/.codex, Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md.
  2. Project. Starting at the project root (usually the Git root) and walking down to your current directory, it takes at most one file per directory: AGENTS.override.md first, then AGENTS.md.
  3. Merge. Files are concatenated from the root down, so guidance closer to where you're working comes later and wins.

There's a size cap. Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. If your instructions are being cut off, split them into nested directories or raise the limit:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536

To check what loaded, ask it, using the command from OpenAI's guide:

codex --ask-for-approval never "Summarize the current instructions."

The one repository of ours that uses AGENTS.md, a client site repo, keeps it to three short paragraphs: read the delivery-status document first, follow the build contract for page work, and take check commands from package.json and the CI workflow. It points at the truth and doesn't copy it. That's the pattern we'd recommend, and the longer argument is in CLAUDE.md vs AGENTS.md.

config.toml: the real shape of a Codex config

Settings live in ~/.codex/config.toml. OpenAI's config documentation lists the layers, highest priority first: CLI flags and -c overrides, a trusted project's .codex/config.toml, a profile file chosen with --profile, your user config, then system defaults.

A minimal file using the documented keys:

# ~/.codex/config.toml
model = "<model-name>"            # choose one with /model
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"             # "live" is the same as --search

Here is the shape of our own file after light use, with identifiers removed. It's instructive because of how little of it is model settings and how much is approval state.

# ~/.codex/config.toml (structure only; connector IDs replaced)
model = "<model-name>"
model_reasoning_effort = "xhigh"

[tui]
screen_reader_detection_done = true

# one table per connector tool we chose to always approve
[apps.<connector-id>.tools."github.create_pull_request"]
approval_mode = "approve"

[marketplaces.mattpocock]
source_type = "git"
source = "https://github.com/mattpocock/skills.git"

[plugins."mattpocock-skills@mattpocock"]
enabled = true

What that shows:

  • Standing approvals live on disk. Our file holds eighteen per-tool entries with approval_mode = "approve", all for connector tools such as creating a branch or opening a pull request. OpenAI's MCP docs list the same per-tool key, with prompt as the cautious value. Read this file now and then. It's the list of things you've stopped supervising.
  • Plugins and marketplaces are config. A marketplace is a Git source; a plugin is enabled by name.
  • One-off overrides don't need an edit. codex -c model_reasoning_effort="high" changes a value for one run.

For separate setups (work and personal, cautious and fast), profiles are files: --profile review layers ~/.codex/review.config.toml on top of the base config. --strict-config makes Codex fail on keys it doesn't recognise, which is a cheap way to catch typos.

MCP servers, skills and plugins

MCP servers connect Codex to outside tools. Add them from the command line; the syntax below matches codex mcp add --help and OpenAI's MCP page:

# a local (stdio) server: the command goes after --
codex mcp add context7 -- npx -y @upstash/context7-mcp

# a remote (streamable HTTP) server
codex mcp add figma --url https://mcp.figma.com/mcp

codex mcp login figma    # OAuth sign-in, if the server needs it
codex mcp list

The same thing in config.toml:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 60

Two documented details worth knowing: the CLI, the desktop app and the IDE extension share this configuration, and project-scoped servers in .codex/config.toml load only for projects you've trusted, because a project-defined MCP server can run commands outside the sandbox. The general idea of MCP is the same in every agent; we explain it in Claude Code MCP servers.

Skills are folders with a SKILL.md file: reusable instructions Codex loads when a task matches. OpenAI's skills page says Codex scans .agents/skills from your working directory up to the repository root, plus $HOME/.agents/skills for personal ones. You invoke one by typing $ or running /skills, or Codex picks it from the description. The format follows the open agent skills standard, which is why the same third-party collection sits in both our Codex and our Claude Code setups. More on the format in our Claude skills guide.

Plugins bundle skills, MCP servers and hooks:

codex plugin marketplace list
codex plugin list
codex plugin add <plugin>@<marketplace>

codex exec: scripts, CI and code review

codex exec is the non-interactive mode. It streams progress to stderr and prints only the final message to stdout, so it pipes cleanly. The flags below are all in codex exec --help.

# read-only by default: safe for questions
codex exec "List the three riskiest files in this diff and why"

# allow edits inside the workspace
codex exec --sandbox workspace-write "Fix the failing lint rules"

# pipe context in; the prompt stays the instruction
npm test 2>&1 | codex exec "Summarize the failures and suggest one fix"

# machine-readable output
codex exec --json "Audit package.json for unused scripts"
codex exec -o result.md "Write release notes for the last 10 commits"

The detail people miss: per OpenAI's non-interactive docs, codex exec runs in a read-only sandbox unless you say otherwise. That's the right default for automation. Other flags that matter in CI are --output-schema <file> to force the final answer into a JSON Schema, --ephemeral to avoid saving session files, and --skip-git-repo-check for directories that aren't repositories.

For authentication in CI, the docs recommend an API key set as CODEX_API_KEY for the single command that needs it, not as a job-wide variable that build scripts could read. For GitHub Actions specifically they point to the official openai/codex-action.

Code review has its own command:

codex review --uncommitted
codex review --base main
codex review --commit <sha>

A caution from running our own scheduled agents (they call a model API from GitHub Actions; they don't use this CLI): an unattended agent should produce a diff or a report for a person to read, never push to production on its own.

Codex CLI vs app vs cloud, and remote control

The names blur together, so here's the map as OpenAI documents it today.

  • CLI. Runs on your machine in a terminal. Best for people who already work there and for automation.
  • Desktop app. OpenAI's app page describes a workspace for running projects in parallel, with a built-in browser, scheduled tasks and computer use. codex app opens it from a terminal. Its help says it "opens the app installer if missing".
  • IDE extension. The same agent inside VS Code and compatible editors, sharing your sign-in with the CLI.
  • Codex Cloud. Tasks run on OpenAI's infrastructure against an environment you define, and keep working while your computer is asleep. It needs a ChatGPT sign-in. From the terminal, codex cloud lists and submits tasks and codex apply applies the latest cloud diff locally. The CLI labels codex cloud experimental.

Remote control. OpenAI's remote connections page describes steering work on your computer from the ChatGPT mobile app or another desktop: start chats, approve commands, review diffs. Setup "starts from the desktop app, not the Codex CLI or IDE extension": Settings, Connections, then scan a QR code with your phone. The host has to stay awake and signed in. The CLI does have codex remote-control with start, stop and pair subcommands, but its own help marks it experimental. We have not used it; treat that as documentation only.

GitHub. Two different things share the word. The CLI's source lives at github.com/openai/codex. The GitHub integration is a hosted feature: connect a repository, then comment @codex review on a pull request, or switch on automatic reviews. It reads review rules from a ## Code Review Rules section in the nearest AGENTS.md.

Where to go from here

If you're setting up Codex CLI this week, do it in this order:

  1. Install, run codex doctor, sign in with the account you already pay for.
  2. Stay in Ask for approval. Leave the sandbox on workspace-write.
  3. Run /init, then cut the AGENTS.md down to what's true and specific.
  4. Add one MCP server you'll actually use. Not five.
  5. Try codex exec on a read-only question before you let it write anything.
  6. After a week, open ~/.codex/config.toml and read what you've auto-approved.

The step people skip is the last one. An agent's permissions grow one "always allow" at a time, and the config file is the only place the whole list is visible.

We set up and supervise coding agents for clients as part of our AI integration work, and we wrote about how that changes delivery in Claude Code for web development. If you want a second opinion on your own setup, get in touch.

Common questions

How do I do a Codex CLI install?

As of November 2026, OpenAI's README gives a standalone installer for macOS and Linux (curl -fsSL https://chatgpt.com/codex/install.sh | sh), a PowerShell installer for Windows, and two package-manager routes: npm install -g @openai/codex and brew install --cask codex. After installing, run codex in a project folder and choose a sign-in method. Run codex --version to confirm the install and codex doctor if anything looks wrong.

What are the main Codex CLI commands?

codex starts the interactive terminal UI. codex exec runs a task non-interactively for scripts and CI. codex review reviews uncommitted changes, a base branch or a commit. codex resume continues a previous session. codex login and codex logout manage credentials. codex mcp manages MCP servers and codex plugin manages plugins. codex update updates the CLI and codex doctor diagnoses the install. Every one of those appears in codex --help on version 0.166.0.

What is Codex CLI auto mode?

There is no mode literally named Auto in OpenAI's documentation as of November 2026. The permission modes are Ask for approval, Approve for me, Full access and Custom. What people usually mean by auto mode is Approve for me, which keeps the workspace-write sandbox and sends eligible approval requests to an automatic reviewer instead of to you. On the command line it is the --approve-for-me flag. The older --full-auto flag is no longer supported, according to the non-interactive mode docs.

Does Codex CLI work on Windows?

Yes. OpenAI's docs say Codex runs natively on Windows through the desktop app, the CLI and the IDE extension, and that its native sandbox means you do not need WSL or a virtual machine. Windows 11 is the recommended baseline and Windows 10 is described as best effort. WSL remains an option when you need Linux tooling. The sandbox has more than one implementation on Windows, so read the Windows sandbox page before you rely on it.

How do I do a Codex CLI update?

Run codex update. The CLI's help describes it as updating Codex to the latest version, and OpenAI's CLI reference says it applies an update when the installed release supports self-update. If you installed with a package manager, upgrading through that package manager also works. OpenAI's CLI page also lists re-running the standalone install script as the update step. Check the result with codex --version.

Codex CLI vs Codex app: which should I use?

They share the same configuration and sign-in, so it is a question of where you work. The CLI suits people who live in a terminal and want to script or automate with codex exec. The desktop app adds a workspace for running projects in parallel, a built-in browser, scheduled tasks and computer use, and remote connections are set up from the app. Codex Cloud runs tasks on OpenAI's infrastructure so they continue while your computer is asleep. Many people start in the CLI and open the app with codex app.

How does Codex CLI remote control and the GitHub integration work?

Remote connections let the ChatGPT mobile app or another desktop steer work on your computer. OpenAI's docs say setup starts from the desktop app by scanning a QR code, and the host must be awake and signed in. The CLI has a codex remote-control command, but its own help marks it experimental. The GitHub integration is separate: you connect a repository to Codex, then comment @codex review on a pull request or switch on automatic reviews. The CLI itself is open source at github.com/openai/codex.