What is the Codex CLI?
The Codex CLI is OpenAI's coding agent for the terminal. You run codex in a project folder, describe a task, and it reads your code, edits files and runs commands on your machine, inside a sandbox, until the task is done. OpenAI's Codex CLI page sums it up as a way to "inspect code, make changes, run commands, and automate repeatable work without leaving your terminal."
The CLI is open source under Apache-2.0 at github.com/openai/codex. It shares its configuration layers with the Codex IDE extension, so settings you make once apply to both. If you are deciding between agents, see Codex vs Claude Code.
How do you install the Codex CLI?
Pick one method. All of these come from the official README and docs.
# npm
npm install -g @openai/codex
# Homebrew (macOS)
brew install --cask codex
# standalone installer (macOS and Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
On Windows, open PowerShell and run the installer from the docs:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
To update, run the same npm or install script command again, or brew upgrade --cask codex for Homebrew. You can also download a binary from the GitHub Releases page and rename it to codex.
Sign in
Run codex for the first time and choose Sign in with ChatGPT. A browser window opens, you log in, and the CLI saves your credentials. OpenAI's authentication docs describe two routes:
- ChatGPT plan: usage counts against your plan. The openai/codex README says this works "as part of your Plus, Pro, Business, Edu, or Enterprise plan." Plan details are on OpenAI's Codex pricing page.
- API key: usage is billed through your OpenAI Platform account at standard API rates. Good for CI and shared machines.
# sign in with an API key read from an environment variable
printenv OPENAI_API_KEY | codex login --with-api-key
# on a remote machine without a browser
codex login --device-auth
# check whether you're signed in (exit code 0 when you are)
codex login status
codex logout removes your saved credentials.
Your first run
Open a terminal in a project and start a session:
cd my-project
codex
Type a request such as "Tell me about this project," then try a small, focused change. You can also pass the first prompt directly, for example codex "explain the auth flow in src/auth".
A few things worth knowing in the session:
- Type
@to search for a file and add its path to your prompt. - Start a line with
!to run a shell command yourself, under the same sandbox rules. - Press Enter while Codex is working to steer the current turn, or Tab to queue a follow-up.
- Press Esc twice with an empty composer to edit your previous message and fork from there.
The Codex CLI docs suggest making a Git checkpoint before and after a task so you can revert changes.
Approval and sandbox modes
Codex controls risk with two settings that work together. The sandbox mode sets what commands can technically do. The approval policy sets when Codex stops to ask you.
| Sandbox mode | What it allows |
|---|---|
read-only |
Read files and run commands that don't write |
workspace-write |
Edit files and run commands inside the workspace; network off by default |
danger-full-access |
No sandbox at all |
Approval policy is on-request (Codex asks when it needs to go past the sandbox) or never.
By default, OpenAI's approvals and security page says, "the agent runs with network access turned off." In a version-controlled folder, Codex recommends the Auto preset, which is workspace-write plus on-request: it edits and runs commands in your project, and asks before touching files outside it or using the network. In a folder that isn't under version control, it recommends read-only.
# the Auto preset, written out
codex --sandbox workspace-write --ask-for-approval on-request
# plan or explore without changing anything
codex --sandbox read-only --ask-for-approval on-request
Inside a session, /permissions switches between presets such as Auto and Read Only. There is also an auto-review option, --approve-for-me, which sends eligible approval requests to a reviewer agent instead of to you. The --yolo flag (long form --dangerously-bypass-approvals-and-sandbox) turns off both the sandbox and approvals; the docs say to use it only inside an externally hardened environment. Codex also keeps .git, .agents, .codex and .aws folders read-only even in workspace-write.
Key flags
These flags work on codex and most subcommands, per the command line reference:
| Flag | What it does |
|---|---|
--model, -m |
Use a different model for this run |
--sandbox, -s |
read-only, workspace-write or danger-full-access |
--ask-for-approval, -a |
on-request or never |
--cd, -C |
Set the working folder before starting |
--add-dir |
Give write access to another folder too |
--image, -i |
Attach screenshots or diagrams to the first prompt |
--search |
Use live web search instead of the default cached results |
--profile, -p |
Layer a named profile file on top of your config |
--config, -c |
Override one config value for this run, such as -c log_dir=./.codex-log |
--oss |
Use a local model through LM Studio or Ollama |
Note that -p means profile in Codex. If you also use Claude Code, where -p means print mode, this one catches people out.
Slash commands worth knowing
Type / in the composer to see them all. The ones you will use most:
| Command | What it does |
|---|---|
/model |
Choose the model and reasoning effort |
/permissions |
Change what Codex can do without asking |
/plan |
Switch to plan mode before implementing |
/init |
Generate an AGENTS.md scaffold in the current folder |
/skills |
Browse and use skills |
/mcp |
List configured MCP tools |
/review |
Review your working tree changes |
/diff |
Show the Git diff, including untracked files |
/compact |
Summarize the chat to free context |
/status |
Show session configuration and token usage |
/usage |
Show your account token usage |
/resume |
Reopen a saved chat |
/import |
Bring in Claude Code or Cursor setup, projects and chats |
From the shell, codex resume --last reopens your most recent chat in the current folder, and codex review --uncommitted runs a review of local changes without opening the TUI.
AGENTS.md: project instructions
Codex reads AGENTS.md files before it starts work. It loads a global file from ~/.codex/AGENTS.md, then walks from the repo root down to your current folder and picks up one AGENTS.md per folder, so files closer to your work take priority. An AGENTS.override.md replaces the regular file in its folder. The combined size is capped by project_doc_max_bytes, 32 KiB by default.
Run /init for a first draft, then edit it to match how your team builds, tests and ships. The AGENTS.md guide covers what to put in it.
config.toml: your Codex settings
Personal defaults live in ~/.codex/config.toml. A repo can add .codex/config.toml, which Codex loads only for trusted projects. The config basics page lists the order: command line flags win, then project config, then a selected profile, then your user config.
A small starting config, using settings from the docs:
# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
# let commands use the network in workspace-write mode
[sandbox_workspace_write]
network_access = true
Leave network_access out if you want the default, network off.
Add MCP servers
Codex connects to Model Context Protocol servers for docs, issue trackers and other tools. Add one from the shell:
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
That writes an entry to ~/.codex/config.toml, which you can also edit by hand:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
Remote servers use --url instead of a command, and codex mcp login <name> handles OAuth for servers that support it. In the TUI, /mcp shows what is active. For ideas, see the best MCP servers.
Use skills
Skills are folders with a SKILL.md file that teach Codex a specific workflow. Codex reads them from .agents/skills in your repo (and parent folders up to the root) and from $HOME/.agents/skills for personal skills. Call one with $skill-name, pick one with /skills, or let Codex choose when your request matches a skill's description. Type $skill-creator to have Codex draft a new one.
The Codex skills guide covers folders, installing and turning skills off. Skills use the same open format as Claude Code, so one folder can serve both.
Run Codex in scripts with codex exec
codex exec runs a task without the interactive UI. Progress goes to stderr and only the final answer goes to stdout, so you can pipe it. The non-interactive mode docs have the details.
# one-off task, output to a file
codex exec "generate release notes for the last 10 commits" | tee release-notes.md
# allow edits (exec is read-only by default)
codex exec --sandbox workspace-write "fix the failing unit tests"
# JSON Lines events for tooling
codex exec --json "summarize the repo structure" | jq
# structured final answer that matches a JSON Schema
codex exec "Extract project metadata" --output-schema ./schema.json -o ./project-metadata.json
codex exec resume --last continues the most recent run. The old --full-auto flag is no longer supported; use --sandbox workspace-write instead. For GitHub Actions, OpenAI recommends its Codex GitHub Action over installing the CLI yourself, and warns against setting API keys as job-level environment variables in workflows that run repository code.
Tips for working with the Codex CLI
- Start in Auto and stay in Git. The default preset plus a clean working tree makes every change easy to inspect with
/diffand easy to undo. - Prefer
--add-dirover full access. When Codex needs another folder, grant that folder rather than dropping the sandbox. - Keep
AGENTS.mdshort. Put standing rules there and move step-by-step procedures into skills, which load only when needed. - Compact long sessions. Run
/compactafter a long run, or/newwhen you switch to unrelated work. - Check limits before a big task.
/statusshows session configuration and token usage, and/usageshows your account usage. - Use profiles for different jobs. A profile file for CI with
approval_policy = "never"keeps your interactive defaults untouched.
Keep your Codex skills somewhere safe
Your AGENTS.md rules and skills are worth more than any one setup on one laptop. Kipt keeps prompts and skills as Markdown in a private GitHub repo you own and installs the library into Codex's .agents/skills with one npx skills add command. If you keep pasting the same prompt into Codex, the free SKILL.md generator turns it into a skill.