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
codexinside 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 inAGENTS.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
codexcommand 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 | shWindows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"npm (any system that has Node.js)
npm install -g @openai/codexHomebrew (macOS)
brew install --cask codexTo 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
- Open a terminal and move into your project folder, for example
cd my-app. - Type
codexand press Enter. - Choose Sign in with ChatGPT (a browser window opens) or sign in with an OpenAI API key.
- Ask for something in plain English, such as
Tell me about this projectorAdd a dark mode switch to the settings page. - Read what Codex plans to do, approve the steps it asks about, then type
/diffto 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.
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:
| Setup | Flags | What Codex may do |
|---|---|---|
| Auto (the preset) | --sandbox workspace-write --ask-for-approval on-request | Read, 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-request | Look around and answer questions. Asks before changing anything. |
| Read-only for CI | --sandbox read-only --ask-for-approval never | Look only, and never stop to ask. Good for automated checks. |
| Auto-review | --sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review | Like 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.
| Command | What it does |
|---|---|
codex | Opens the interactive screen in the current folder |
codex resume | Continues a previous session |
codex fork | Copies a saved session into a new chat |
codex exec | Runs a task with no human input (short form codex e) |
codex review | Runs a code review without the interactive screen |
codex mcp | Adds and manages MCP servers (connectors to outside tools) |
codex plugin | Installs, lists and removes plugins |
codex cloud | Browses or starts Codex Cloud tasks from the terminal |
codex apply | Copies the latest change from a cloud task into your files |
codex agents | Opens the agent command center |
codex app | Opens the ChatGPT desktop app on macOS or Windows |
codex doctor | Writes a health report for install, config and sign-in |
codex update | Checks 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 command | Use it to |
|---|---|
/init | Create a starter AGENTS.md file for your project |
/model | Pick the model and how hard it should think |
/permissions | Change what Codex may do without asking |
/plan | Switch to plan mode, so you get a plan before any edits |
/diff | See the Git diff, including brand new files |
/review | Ask Codex to review the changes in your folder |
/mention | Attach a file to the chat |
/compact | Summarise a long chat so it takes up less room |
/status | Show the current settings and token use |
/usage | See how much of your plan you have used |
/worktree | Carry on in a separate Git worktree |
/goal | Set a goal for a longer task, then pause or resume it |
/side | Open a side chat without derailing the main one |
/import | Bring in your Claude Code or Cursor setup and chats |
/new, /resume, /fork | Start fresh, reopen an old chat, or branch off |
/quit | Leave 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 = trueCodex can read settings from several places. When two disagree, the higher one in this list wins (from OpenAI's config docs):
- Flags you type, including one-off overrides such as
-c model_reasoning_effort="high". - A
.codex/config.tomlinside your project, loaded only for projects you have marked as trusted. - A profile file such as
~/.codex/review.config.toml, chosen with--profile review(the pattern is~/.codex/<name>.config.toml). - Your personal
~/.codex/config.toml. - 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
~/.codexforAGENTS.override.md, thenAGENTS.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_bytesin config.toml or split long rules into subfolders. - Other file names: list them in
project_doc_fallback_filenamesif your team already keeps rules in a file such asTEAM_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-onlykeeps 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-checklets it run in a folder that isn't a Git project.--output-schema file.jsonforces the final answer to follow a JSON shape you define.--ephemeralstops it saving the session to disk.--worktreeruns 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:
| Plan | Price | Codex CLI included? |
|---|---|---|
| Free and Go | $0 and $8/month | No. Codex in the desktop app only, for lighter tasks, subject to rollout |
| Plus | $20/month | Yes, along with web, IDE and iOS |
| Pro | From $100/month (tiers at $100, $200 and $500) | Yes, with more usage |
| Business | $20 per user/month billed yearly, $25 monthly | Yes, with a team workspace |
| API key | Pay per token used | Yes, 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 see | What to do |
|---|---|
| Something is wrong but you can't tell what | Run codex doctor and read the report |
| Windows says the sandbox is degraded | Type /setup-default-sandbox to set up the admin-approved Windows sandbox |
codex exec refuses to run in a folder | The folder isn't a Git project. Add --skip-git-repo-check or run git init |
| The chat is long and answers get worse | Type /compact, or /new for a clean start |
| The automatic reviewer blocked a step you want | Type /approve to let Codex retry that one action |
| Rules at the end of AGENTS.md are ignored | The 32 KiB limit was hit. Shorten the file or raise project_doc_max_bytes |
| A setting has no effect | Type /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 startedKeep reading
Windows setup
Codex on Windows: the app or the CLI, and how to set up each one
Head to head
Codex vs Claude Code: seven rounds and an honest verdict
Three-way comparison
Claude Code vs Codex vs Gemini: the three CLI coding agents compared
Explainer
Agentic coding, explained in plain English
Buyer's guide
The best AI coding agents in 2026, sorted by how you work