Command reference

Codex CLI command reference: from install to codex exec

Updated November 17, 202610 min read

Codex CLI is OpenAI Codex running in your terminal: you type a request, and it reads your project, edits files and runs commands while you decide how much it may do on its own. This page is laid out by task, with the real commands for each step as of November 2026. Keep it open next to your terminal and jump to the part you need.

Codex CLI at a glance

  • Install with npm install -g @openai/codex, or with OpenAI's script for Mac, Linux or Windows.
  • Run codex inside a project folder and sign in with your ChatGPT account or an API key.
  • The Auto preset lets Codex edit inside your project and asks before it goes outside it or online.
  • Personal settings live in ~/.codex/config.toml. Project rules live in AGENTS.md.
  • Scripts and CI pipelines use codex exec, which runs a task with no questions asked.
  • Included with ChatGPT Plus ($20/month) and higher plans, as of November 2026.

OpenAI Codex and where the CLI fits

OpenAI Codex is the name of OpenAI's coding agent. You can reach the same agent, with the same account and the same usage allowance, from four places:

Codex CLI
The codex command in your terminal. It works on the files on your own computer. This page is about it.
Codex app
Codex inside the ChatGPT desktop app on macOS and Windows, with projects and several chats side by side.
IDE extension
Codex as a side panel inside VS Code, Cursor or Windsurf.
Codex Cloud
Tasks that run on OpenAI's servers instead of your machine, started from chatgpt.com/codex.

The CLI is the most flexible of the four. It uses whatever tools are already installed on your computer, it can be called from scripts, and its source code is public on GitHub. If you have never used a terminal coding agent before, our agentic coding guide explains the idea in plain words first.

Codex CLI install commands for each system

Pick the line that matches your computer. Each one comes from OpenAI's Codex CLI docs.

macOS and Linux

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm (any system that has Node.js)

npm install -g @openai/codex

Homebrew (macOS)

brew install --cask codex

To update later, run codex update, run the same install line again, or use brew upgrade --cask codex if you installed with Homebrew. If anything feels broken after an install, codex doctor writes a report that checks your install, settings, sign-in and runtime in one go.

Tip

On Windows there are extra choices, such as running Codex inside WSL2 (a Linux system inside Windows) and three different sandbox types. Our Codex on Windows page walks through them.

First run: signing in and giving Codex a task

  1. Open a terminal and move into your project folder, for example cd my-app.
  2. Type codex and press Enter.
  3. Choose Sign in with ChatGPT (a browser window opens) or sign in with an OpenAI API key.
  4. Ask for something in plain English, such as Tell me about this project or Add a dark mode switch to the settings page.
  5. Read what Codex plans to do, approve the steps it asks about, then type /diff to see every file it changed.

You can also hand Codex its first request on the same line: codex "fix the failing login test". To show it a screenshot or a sketch, add --image shot.png. To let it look things up online for that run, add --search.

Two account commands are handy when you share a computer or switch between a ChatGPT login and an API key: codex login signs you in, and codex logout removes the saved sign-in.

A simple habit saves a lot of pain: make a Git commit (a saved snapshot of your project) before each task and after it. If you dislike what Codex did, you can go straight back.

Codex approval modes and sandbox settings

Codex has two separate dials. The sandbox decides what the agent can physically reach: only reading, writing inside your project, or everything. The approval policy decides when Codex stops and asks you. OpenAI's security page lists these combinations as of November 2026:

SetupFlagsWhat Codex may do
Auto (the preset)--sandbox workspace-write --ask-for-approval on-requestRead, edit and run commands inside your project. Asks before editing outside it or using the network.
Safe read-only browsing--sandbox read-only --ask-for-approval on-requestLook around and answer questions. Asks before changing anything.
Read-only for CI--sandbox read-only --ask-for-approval neverLook only, and never stop to ask. Good for automated checks.
Auto-review--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_reviewLike Auto, but an automatic reviewer answers the approval requests instead of you.
Full access--dangerously-bypass-approvals-and-sandbox (short form --yolo)No sandbox and no questions. OpenAI marks it as not recommended.

The sandbox names are read-only, workspace-write and danger-full-access. The approval names are on-request and never, and -a is the short form of --ask-for-approval. You can change your mind halfway through a chat: type /permissions to loosen or tighten what Codex may do without asking. In Auto-review mode, /approve lets Codex retry one action that the automatic reviewer turned down.

Watch out

Older guides mention an untrusted approval policy. OpenAI has retired it and says it can stop Codex from starting, so delete it from any old config file you copied.

Codex CLI commands typed in the terminal

These are the commands you type before a session starts, straight after codex. OpenAI's command reference has the full list.

CommandWhat it does
codexOpens the interactive screen in the current folder
codex resumeContinues a previous session
codex forkCopies a saved session into a new chat
codex execRuns a task with no human input (short form codex e)
codex reviewRuns a code review without the interactive screen
codex mcpAdds and manages MCP servers (connectors to outside tools)
codex pluginInstalls, lists and removes plugins
codex cloudBrowses or starts Codex Cloud tasks from the terminal
codex applyCopies the latest change from a cloud task into your files
codex agentsOpens the agent command center
codex appOpens the ChatGPT desktop app on macOS or Windows
codex doctorWrites a health report for install, config and sign-in
codex updateChecks for and installs a newer CLI

Codex slash commands worth learning first

Inside a session, type / and Codex shows every slash command. There are dozens. These are good ones to learn first:

Slash commandUse it to
/initCreate a starter AGENTS.md file for your project
/modelPick the model and how hard it should think
/permissionsChange what Codex may do without asking
/planSwitch to plan mode, so you get a plan before any edits
/diffSee the Git diff, including brand new files
/reviewAsk Codex to review the changes in your folder
/mentionAttach a file to the chat
/compactSummarise a long chat so it takes up less room
/statusShow the current settings and token use
/usageSee how much of your plan you have used
/worktreeCarry on in a separate Git worktree
/goalSet a goal for a longer task, then pause or resume it
/sideOpen a side chat without derailing the main one
/importBring in your Claude Code or Cursor setup and chats
/new, /resume, /forkStart fresh, reopen an old chat, or branch off
/quitLeave Codex

A worktree, used by /worktree, is a second copy of your project folder that Git keeps linked to the first, so an experiment can't touch your main files. We explain it properly in our worktrees guide; the idea is the same for Codex.

The Codex config file: config.toml

Codex reads its settings from plain text files in TOML format (simple name = value lines). The main one is ~/.codex/config.toml, which on Windows is %USERPROFILE%\.codex\config.toml. A small, sensible starting file looks like this:

# How hard the model thinks by default
model_reasoning_effort = "medium"

# Stop and ask before running commands that need it
approval_policy = "on-request"

# Let Codex write inside the project folder only
sandbox_mode = "workspace-write"

# Allow network access from inside the sandbox
[sandbox_workspace_write]
network_access = true

Codex can read settings from several places. When two disagree, the higher one in this list wins (from OpenAI's config docs):

  1. Flags you type, including one-off overrides such as -c model_reasoning_effort="high".
  2. A .codex/config.toml inside your project, loaded only for projects you have marked as trusted.
  3. A profile file such as ~/.codex/review.config.toml, chosen with --profile review (the pattern is ~/.codex/<name>.config.toml).
  4. Your personal ~/.codex/config.toml.
  5. Defaults sent by your workspace admin, then system settings, then Codex's built-in defaults.

If a setting doesn't seem to apply, type /debug-config in a session. It prints each layer Codex loaded, so you can see which file won.

Codex AGENTS.md: standing instructions for every task

AGENTS.md is a plain text file of house rules that Codex reads before it starts work: how to build and test the project, the coding style you want, and anything it must never touch. Run /init and Codex writes a first draft for you. Here is a short example:

# AGENTS.md

## Commands
Install: npm install
Test: npm test
Start the app: npm run dev

## Rules
Use TypeScript for new files.
Never edit anything in the migrations folder.
Ask before adding a new package.

How Codex finds AGENTS.md files

  • Your personal file: Codex first checks ~/.codex for AGENTS.override.md, then AGENTS.md, and uses the first one that isn't empty.
  • Your project: it starts at the project root (usually the Git root) and walks down to the folder you are in, taking at most one file per folder.
  • Order: files nearer to your current folder are read later, so their advice wins over the general rules higher up.
  • Size limit: it stops adding files once they reach 32 KiB in total. Raise project_doc_max_bytes in config.toml or split long rules into subfolders.
  • Other file names: list them in project_doc_fallback_filenames if your team already keeps rules in a file such as TEAM_GUIDE.md.

Details are on OpenAI's AGENTS.md page. Other agents read AGENTS.md too. Antigravity CLI reads it, and Claude Code reads it when a project has no CLAUDE.md, so one well-written file can serve several tools.

Codex agents and subagents

People searching for Codex agents usually mean one of two things. codex agents (or /agents inside a session) opens a command center where you browse and switch between your Codex chats, and /subagents switches to a helper thread that Codex started for part of a bigger job.

Note

The Codex command center only shows Codex. If you also keep Claude Code or Gemini busy, VibeCodingDeck puts your installed Codex CLI in a desktop grid next to them, up to 12 panes, with a light on each pane that turns on when an agent is waiting for your answer.

Running Codex non-interactively with codex exec

codex exec runs one task from start to finish with nobody at the keyboard. It is meant for scripts, scheduled jobs and CI pipelines (the automatic checks that run when you push code). A few real examples:

# Run one task and print the result
codex exec "update the README with the new install steps"

# Machine-readable output, one JSON event per line
codex exec --json "list every TODO comment"

# Save only the final answer to a file
codex exec -o summary.md "summarise what changed this week"

# Continue the most recent exec session with a follow-up
codex exec resume --last "now add tests for it"
  • --sandbox read-only keeps a job from editing anything, which is the safe choice for checks and reports.
  • --cd path (or -C) runs the task in another folder.
  • --model (or -m) picks a different model for this one run.
  • --skip-git-repo-check lets it run in a folder that isn't a Git project.
  • --output-schema file.json forces the final answer to follow a JSON shape you define.
  • --ephemeral stops it saving the session to disk.
  • --worktree runs the job in its own managed Git worktree.

For a review without edits, codex review is often simpler than writing an exec prompt. Only use --yolo with exec on a throwaway machine, such as a fresh CI runner that is deleted after the job.

Codex CLI pricing (as of November 2026)

The CLI itself costs nothing to install. What you pay for is the ChatGPT plan or API usage behind it. From OpenAI's pricing page:

PlanPriceCodex CLI included?
Free and Go$0 and $8/monthNo. Codex in the desktop app only, for lighter tasks, subject to rollout
Plus$20/monthYes, along with web, IDE and iOS
ProFrom $100/month (tiers at $100, $200 and $500)Yes, with more usage
Business$20 per user/month billed yearly, $25 monthlyYes, with a team workspace
API keyPay per token usedYes, but no cloud features

Type /usage in a session to see how much of your allowance is left. If you are weighing Codex against Anthropic's agent, our Codex vs Claude Code page compares cost and quality, and Claude Code vs Codex vs Gemini adds Google to the mix.

Fixes for common Codex CLI problems

What you seeWhat to do
Something is wrong but you can't tell whatRun codex doctor and read the report
Windows says the sandbox is degradedType /setup-default-sandbox to set up the admin-approved Windows sandbox
codex exec refuses to run in a folderThe folder isn't a Git project. Add --skip-git-repo-check or run git init
The chat is long and answers get worseType /compact, or /new for a clean start
The automatic reviewer blocked a step you wantType /approve to let Codex retry that one action
Rules at the end of AGENTS.md are ignoredThe 32 KiB limit was hit. Shorten the file or raise project_doc_max_bytes
A setting has no effectType /debug-config to see which file overrides it

Codex CLI questions, answered briefly

How do I install Codex CLI?

+

Run npm install -g @openai/codex, or use OpenAI's script: curl -fsSL https://chatgpt.com/codex/install.sh | sh on Mac and Linux, or the PowerShell line on Windows. Then type codex in a project folder.

Is Codex CLI free?

+

The program is free and open source, but using it needs ChatGPT Plus ($20/month) or higher, or an OpenAI API key billed per use, as of November 2026.

What are the Codex approval modes?

+

The approval policy is on-request (ask when needed) or never (don't ask). It pairs with a sandbox of read-only, workspace-write or danger-full-access. The default Auto preset is workspace-write with on-request.

Where is the Codex config file?

+

Your personal settings are in ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows). A project can add its own .codex/config.toml, which loads only for trusted projects.

What does codex exec do?

+

It runs a single task without asking you anything, then exits. Add --json for structured output or -o file to save just the final answer.

Sources

Run up to 12 AI coding agents in one window.

Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.

Get started

Keep reading