Codex CLI: what it is, how to install it, and how to use it

What is Codex CLI?

Codex CLI is a coding agent from OpenAI that you run inside a terminal, in the folder of a project. You describe a task in plain English. It reads the files it needs, proposes edits, runs commands such as your test suite, and shows you the diff. OpenAI's own description is that it lets you inspect, edit and run code from your terminal. The source is public at github.com/openai/codex under the Apache-2.0 license.

It is one surface of a larger product called Codex. The same agent also runs in a desktop app, an IDE extension and in the cloud. The CLI is the one to pick when you already live in a terminal, want to script the agent, or want it to run in CI. If you want the product overview instead of the command-line tool, read what OpenAI Codex is.

Codex CLI is a tool for people who are comfortable reading a diff. If you cannot read code at all, a browser-based builder is a better start. The board has an idea page for developer tools if you want something to point the agent at.

How do you install Codex CLI?

OpenAI documents four ways to install it. All of them give you the same codex command. The shell and PowerShell installers need no Node.js. The npm route needs it.

The docs say to start the Windows installer from a new PowerShell window. Piping a script from the internet into a shell is a trade-off: the installers download from OpenAI's release host and fall back to GitHub Releases, per the repository README. If you prefer to read before you run, download the script first, open it, then execute it. You can also download a binary from the latest GitHub release.

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

# check it is on your PATH
codex --version

# go to a project and start it
cd ~/code/my-project
codex

# update later: run the installer again
curl -fsSL https://chatgpt.com/codex/install.sh | sh

How do you sign in to Codex CLI?

Open a project folder and run codex. The first time, choose Sign in with ChatGPT. A browser window opens, you sign in, and the browser hands credentials back to the CLI. You can also run codex login directly. The authentication page lists two methods for local work: a ChatGPT sign-in for subscription access, or an API key for usage-based access.

# put the key in an environment variable first (never in a file you commit)
export OPENAI_API_KEY="your-key-here"

# pipe it to codex login
printenv OPENAI_API_KEY | codex login --with-api-key

# confirm which method is active (exit code 0 when credentials exist)
codex login status

# clear stored credentials
codex logout

The two methods are billed differently, and they do not give the same features. With an API key, usage is billed to your OpenAI Platform account at standard API rates instead of drawing on your plan's included credits. The docs also say that features relying on ChatGPT workspace access or cloud services are limited or unavailable on an API key. Cloud tasks require a ChatGPT sign-in. The docs recommend API-key sign-in for CI jobs and say not to expose Codex execution in untrusted or public environments.

How do you run your first task?

Start with a task that is easy to check, so you learn how the tool behaves before you trust it with a big change.

1. Commit your current state. A clean working tree makes the diff easy to read.
2. Run `codex` in the project root. The banner shows the model, the directory and a few starter commands such as /init, /status, /permissions, /model and /review.
3. Ask it to explain before it edits. The docs suggest a prompt as plain as “Tell me about this project”. Check that its summary matches what you know.
4. Give one focused change. Name the file, the behavior and the test that should pass. Type @ to search for a file and add its path to the prompt.
5. Read each proposed command and diff. Approve, decline, or type a correction. Press Enter while it works to inject new instructions into the current turn.
6. Run `/diff`, then `/review`. /diff shows the Git diff including untracked files. /review asks Codex to look over your working tree for behavior changes and missing tests.
7. Commit. Then start the next task from a clean state.

In this repository, add input validation to the signup form in src/components/SignupForm.tsx.

Behavior: reject empty names and emails without an @ sign, and show the error under the field.
Do not change the API route or add new dependencies.
Done when: the existing tests pass and you have added two tests for the new rules. Run the test command and show me the result before you stop.

For the general craft of writing a brief like this, see how to write an app build prompt. Every idea on the board comes with a generated build prompt in the same spirit that you can paste straight into a terminal agent.

What are Codex CLI's approval modes and sandbox settings?

Codex separates two controls. The sandbox mode decides what the agent can do technically: where it can write and whether it can reach the network. The approval policy decides when it must stop and ask you. By default, the agent runs with network access off, and the sandbox limits writes to the current workspace, per the approvals and security page.

Switch presets in a session with /permissions. The picker offers Auto, Read Only and, where you have named profiles, those too.

• Default start. In a Git-tracked folder Codex starts in Auto. In a folder without version control it starts read-only, and may stay read-only until you trust the directory.
• Protected paths. Even in a writable root, the .git, .agents, .codex and .aws directories are read-only.
• Network access. Off by default in the workspace-write sandbox. Turn it on in config with network_access = true under [sandbox_workspace_write], and consider the network proxy feature to allow only named domains.
• Retired setting. The older untrusted approval policy is no longer supported, and a leftover approval_policy = "untrusted" can stop the client from starting. Remove it from your config.
• Extra folders. To let the agent write somewhere else, prefer --add-dir over switching to full access.

What are the core Codex CLI commands?

There are two layers: commands you type in your shell, and slash commands you type inside a running session. Type / to open the slash list and keep typing to filter it. While Codex is working, Tab queues a command for the next turn.

Two shortcuts are worth learning on day one. Prefix a line with ! to run a local shell command under your current approval and sandbox settings. Press Escape twice with an empty prompt to edit your previous message and fork the chat from that point. The full list sits in the developer commands reference.

What is AGENTS.md and how does Codex use it?

AGENTS.md is a plain Markdown file of standing instructions. Codex reads it before it does any work, so you do not repeat yourself in every prompt. Run /init to create a first version, then edit it. The rules for discovery come from the AGENTS.md guide.

1. Global. In your Codex home folder (~/.codex unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. It uses only the first non-empty file at this level.
2. Project. From the project root (usually the Git root) down to your current directory, it checks each folder for AGENTS.override.md, then AGENTS.md, then any fallback names you configured. At most one file per folder.
3. Merge. Files are joined from the root down, so the file closest to where you are wins on conflict.

Codex stops adding files once the combined size reaches 32 KiB by default (the project_doc_max_bytes setting). Keep the file short enough to be read, and put team-specific rules in nested folders. For a longer treatment of the format, which other tools also read, see the guide to AGENTS.md.

# AGENTS.md

## What this project is
[Two sentences: who uses it and what it does.]

## Commands
- Install: pnpm install
- Dev server: pnpm dev
- Tests: pnpm test (run before saying a task is done)
- Lint: pnpm lint

## Rules
- Make the smallest change that satisfies the task.
- Do not add dependencies without asking.
- Never write secrets into source files. Read them from environment variables.
- Do not edit generated files or anything under /migrations without asking.

## Out of scope for now
[Your later list: written down so the agent does not build it.]

How do you run Codex CLI in scripts and CI?

codex exec runs one task and exits. By default it uses a read-only sandbox, so a script that only needs analysis is safe by default. Grant the least you need for the job, per the non-interactive mode docs.

# analysis only (default sandbox is read-only)
codex exec "summarize the repo structure"

# allow edits inside the workspace
codex exec --sandbox workspace-write "fix the failing lint errors"

# pipe input in
curl -s https://example.com/data.json | codex exec "format the top 20 items into a markdown table" > table.md

# newline-delimited JSON events for tooling
codex exec --json "summarize the repo structure" | jq

# CI: capture progress and a final summary
codex exec --json --output-last-message summary.txt "review the diff for risky changes"

• `--full-auto` is gone. The docs say it is no longer supported. Use --sandbox workspace-write, or --approve-for-me to send approval requests through automatic review.
• Reproducible runs. --ignore-user-config skips your personal config.toml, and --ignore-rules skips execution-policy rule files.
• Use an API key in CI. Create a key for the job, store it as a secret, and run codex login --with-api-key from stdin.

How much does Codex CLI cost?

The tool is free to install. What you pay for is the model usage behind it. As of October 2026, the Codex pricing page lists these routes.

Included usage is not a fixed message count. The pricing page gives local-message estimates per five-hour window for Plus and standard Business, which vary by model, and says Pro plans currently have no five-hour limit. It also says cloud tasks can use more of your allowance than local messages, and that API token prices should not be used to estimate what a subscription includes. Check the usage dashboard for your real limits.

What should you build with Codex CLI?

Pick a task with a clear finish line, like “add this validation and make the tests pass”, and run it in Auto. Terminal agents are strongest at tasks with a fast feedback loop: a failing test, a linter, a type error, a build that either passes or does not.

• A small tool nobody has built yet. Browse the developer-tools ideas on the board. One posted idea asks for a way to see which of your abandoned repos is closest to finished. Every idea has a ready build prompt you can paste into Codex.
• A chore you do by hand. Changelogs, dependency bumps, test scaffolding.
• Reviews of your own diffs. /review before every commit costs little and catches missed tests.

If you have an idea you will never build yourself, you can post it on the board for someone with a terminal agent to pick up. To compare Codex with Anthropic's equivalent, read Claude Code vs Codex.