Codex CLI is OpenAI's open-source coding agent for the terminal. You open it inside a project, describe a task in plain English, and it reads your files, proposes edits, runs commands and tests, and reports back. It can work carefully with you approving each step, or run on its own inside a sandbox while you do something else. This guide has 10 sections, 15 copy-paste blocks of prompts or commands, an 8-question Q&A, and takes about 26 minutes to read.

This codex cli tutorial takes you from a clean machine to a merged pull request. You will install the CLI, sign in, pick a sandbox and approval mode, write an AGENTS.md file, complete a first real task, hand a PR review to Codex, and connect it to GitHub and your IDE. There is also a short comparison with Claude Code and a section on the errors people hit most.

Everything here reflects Codex as it works in late 2026. OpenAI ships updates often, so when a flag or menu on your screen looks different, run codex --help and trust that over any article, including this one. If you want structured practice instead of a single read, the AI Mastery course has a full Codex module with quizzes at the end of each lesson.

OpenAI uses the name Codex for two products that share a model and an instructions format but run in different places. Knowing which one you are using saves confusion later, because the commands, the permissions and the way results come back are not the same.

The two share AGENTS.md. Instructions you write once for the CLI also guide the cloud agent, so the file is worth doing properly. Most developers use the CLI for interactive work and quick fixes, and the cloud agent for batch tasks that can run unattended. If you have used Claude Code, the split is similar to Claude Code in the terminal versus Claude Code on the web; our Claude Code tutorial for beginners walks through that side.

You need a terminal, Node.js (a current LTS release) and git. On Windows, use WSL. Install the CLI globally with npm:

npm install -g @openai/codex

On macOS, Homebrew works too:

brew install codex

Check that the command is on your path.

codex --version

Now sign in. Run the command with no arguments.

codex

The first launch asks how you want to authenticate.

Choose Sign in with ChatGPT to use the Codex access bundled with a paid ChatGPT plan; it opens a browser window, you approve, and the token is stored under ~/.codex/. Choose the API key option if you bill through an OpenAI Platform account instead, and export OPENAI_API_KEY in your shell before launching. Check the current pricing page for what each plan includes, since limits change.

Run codex login later to switch accounts and codex logout to clear the stored credential. Configuration lives in ~/.codex/config.toml, where you can set a default model, a default approval policy and MCP servers. You do not need to touch it yet.

One habit to build now: always start Codex from the root of the project you are working on. It treats the current directory as its workspace, and the sandbox boundaries in the next section are drawn around that folder.

Codex CLI separates two questions: what can the agent touch (the sandbox) and when does it stop to ask you (the approval policy). Most beginners assume these are one setting. They are not, and picking the right pair is the single biggest safety decision you make.

The sandbox has three levels. read-only lets Codex read files and run commands that do not write, which is perfect for code review and questions. workspace-write allows edits and writes inside the current project directory and its temp folders, but blocks the rest of your disk and, by default, network access. danger-full-access removes the sandbox; only use it inside a container you can throw away.

The approval policy decides when Codex pauses. With untrusted, it asks before running anything except a short list of known-safe commands. With on-request, the model decides when it needs to ask, usually for anything outside the sandbox. With on-failure, it runs freely inside the sandbox and only asks if a sandboxed command fails and it wants to retry with more permission. With never, it never asks, so pair that only with a strict sandbox.

You can set both from the command line, and there are shortcuts. Start a cautious session like this:

codex --sandbox workspace-write --ask-for-approval untrusted

Or use the shortcut for supervised automation.

codex --full-auto

Codex looks for the file in layers. A global file at ~/.codex/AGENTS.md applies to every project, a file at the repo root applies to that repo, and files in subfolders apply when Codex works inside them. More specific files win when instructions conflict. Keep the global file for personal preferences and the repo file for team rules.

The fastest way to start is inside a session.

/init

That drafts a starter file from your project. Edit it before trusting it.

A good file is short and specific. Commands beat descriptions. Here is a compact example for a TypeScript service:

# AGENTS.md

## Setup
- Install: `npm ci`
- Dev server: `npm run dev` (port 3000)
- Tests: `npm test` (must pass before you finish)
- Lint: `npm run lint --fix`

## Rules
- Never edit files under `migrations/` or `.env*`
- Use the existing `logger` module, not console.log
- Keep functions under 40 lines; extract helpers
- Write a failing test before fixing a bug

## Finishing
- Run tests and lint, then summarize changed files
- Do not commit; leave changes staged for review

Notice what is missing: no essays about architecture, no wishes.

Every line is something Codex can act on or check. Add a "do not" section for anything that has burned you before. If Codex keeps doing something you dislike, the fix is usually one more line in this file rather than a longer prompt. The pattern is identical to a CLAUDE.md file, which we cover in the Claude Code skills guide, and the course lesson on agent instruction files shows several real examples side by side.

Time for a real task. Pick something small with a clear finish line. A good first task changes two or three files and has a test you can run. Below, the example is adding input validation to an API route, but any similar job works.

git status
codex --sandbox workspace-write --ask-for-approval untrusted

A prompt like this gets far better results than "add validation": "In src/routes/users.ts, the POST handler accepts any body. Add validation so email is required and well-formed and name is 2 to 80 characters. Return 400 with a JSON error listing the failing fields. Add tests in tests/users.test.ts following the existing pattern. Run the test suite when you are done."

/diff

Then check the working tree yourself.

git diff --stat

codex resume

That shows recent sessions and lets you reopen one.

For scripted or CI use there is a non-interactive mode that runs one task and exits, printing the result to standard output:

codex exec "update the README installation section to match package.json scripts"

Use exec only with a sandbox and a clear task.

Code review is one of the best uses of Codex because it needs no write access and produces value on every run. Check out the branch you want reviewed, or fetch a colleague's pull request, and open a read-only session.

git fetch origin pull/128/head:pr-128
git checkout pr-128
codex --sandbox read-only

Inside the session, ask for the review with a clear frame.

Try: "Review the diff between this branch and main. Focus on correctness, error handling and anything that would break existing callers. For each issue give file, line, severity and a suggested fix. Do not comment on formatting." Codex will run git diff main...HEAD, read the changed files and the surrounding code, and give you a structured list. Newer builds also expose a built-in review command:

/review

It reviews your current changes against the base branch.

The output is a starting point, not a verdict. Ask follow-ups: "is the race condition you flagged reachable in the current request lifecycle?" Codex reads more of the codebase to answer, which is exactly what a careful human reviewer would do. When you agree with a finding, you can switch to workspace-write and ask it to apply the fix on the spot.

For a team workflow, put the review instructions into AGENTS.md under a "Review checklist" heading. Then every reviewer, human or agent, uses the same list. This also feeds the GitHub integration in the next section, where Codex reviews pull requests without anyone opening a terminal.

The GitHub integration is what turns Codex from a personal tool into a team workflow. Setup happens in ChatGPT: open the Codex section, connect your GitHub account, and choose the repositories Codex may access. Grant only the repos you need; you can add more later.

Once connected, three things become possible. First, you can start cloud tasks from ChatGPT against any connected repo, and Codex opens a pull request with its changes when finished. Second, you can mention Codex on a pull request in GitHub, for example by commenting @codex review this, and it posts a review in the PR thread. Third, you can enable automatic reviews so every new pull request gets a first pass before a human looks.

Because both the CLI and the cloud agent read the same AGENTS.md, the instructions you tuned locally carry over. If your file says "run npm test before finishing", the cloud container runs it too, provided the environment can install your dependencies. You configure that environment in the ChatGPT Codex settings: setup script, environment variables and whether network access is allowed during the task.

A practical rhythm many teams settle on: write the issue clearly, assign it to Codex cloud, get a draft PR, then pull that branch locally and finish it with the CLI where you can run the app. The cloud agent does the boring first eighty percent, and you keep the judgement calls.

If you prefer a sidebar to a terminal, OpenAI ships a Codex extension for VS Code, which also works in VS Code forks such as Cursor and Windsurf. Install it from the extension marketplace, sign in with the same ChatGPT account, and it uses your existing ~/.codex configuration and AGENTS.md files.

The extension shows the conversation in a panel, presents edits as inline diffs you accept or reject, and lets you switch between local mode and cloud tasks from the same window. Selecting code and asking a question about it is quicker than typing file paths in the terminal, and you can open the built-in terminal alongside to keep the CLI habits you learned above.

For JetBrains users, check the official docs for current IDE support; the extension list grows over time and this article will not guess at it. Whatever the surface, the mental model is unchanged: sandbox, approval policy, instructions file, small tasks with a test.

People ask which terminal agent to learn. The honest answer is that Codex CLI and Claude Code are closer than either vendor's marketing suggests. Both run in your terminal, read your repo, ask permission before risky actions, read a Markdown instructions file, support MCP servers for external tools, and have an IDE extension and a cloud counterpart. The differences are in defaults and ecosystem.

Codex ties naturally to ChatGPT plans and to GitHub, and its sandbox model is explicit and easy to reason about. Claude Code leans on Anthropic's Claude models and has a deeper customization layer: plan mode, hooks, subagents, and Skills, which are reusable SKILL.md procedures the agent loads when relevant. Start with the ecosystem you already pay for; the concepts transfer in an afternoon. For the long form, read what Claude Code is and the Gemini CLI tutorial, since Google's open-source agent is the third option on the same shelf.

Check both official pricing pages before deciding; plan limits shift often.

Two more problems deserve a paragraph. The first is a rate limit or usage cap message mid-task. Codex stops and tells you; nothing is lost. Wait for the window to reset, or switch to an API key if your team bills that way. Check the current pricing page rather than guessing what your plan includes.

The second is git confusion: Codex edited files but the diff is empty, or the change sits on the wrong branch. Almost always the session started in a different directory than you thought. Run /status to see the working directory and sandbox, then git status in that folder. Starting every session from the repo root avoids this.

When you hit anything not covered here, the official docs at OpenAI's developer site are current and searchable, and the CLI's own codex --help is the source of truth for flags. Beyond that, the fastest way to get fluent is practice with feedback, which is exactly what the AI Mastery course Codex lessons are built for, and the guide to building your first AI agent explains the plan, act, observe loop that Codex runs under the hood.

Official references: OpenAI Codex documentation and the open-source Codex CLI repository.