# How to use Codex CLI: a step-by-step guide

URL: https://agentvera.dev/en/blog/how-to-use-codex-cli/ · Published: 2026-10-25

How to use Codex CLI: install it, sign in with ChatGPT, pick sandbox and approval modes, write AGENTS.md, set up config.toml and MCP, and resume sessions.

**In short:**

- Install Codex CLI with the official script, npm or Homebrew, run codex in a project folder and sign in with your ChatGPT account or an API key.
- The default Auto mode lets Codex edit and run commands inside the workspace and asks before it touches anything outside it or the network; /permissions switches to read-only.
- Project rules go in AGENTS.md, settings in ~/.codex/config.toml, MCP servers are added with codex mcp add, and codex resume picks up an earlier session.

To use Codex CLI, install it with one command, run `codex` inside a project folder, sign in with your ChatGPT account, and then describe the change you want in plain English. Codex reads the code, edits files and runs commands inside your project, and asks before it reaches outside the folder or onto the network.

That’s the core loop. This guide covers the rest: approval and sandbox modes, an `AGENTS.md` file, `config.toml`, MCP servers, the commands you’ll use every day, resuming sessions and a few habits that make Codex more reliable. Everything here follows OpenAI’s official Codex documentation as of October 2026.

## What Codex CLI is

Codex CLI is OpenAI’s coding agent for the terminal. It runs locally, works on the folder you start it from and can run your tests, linters and git. The same Codex also exists as an IDE extension, a desktop app and a cloud version, and they share your sign-in. If you’re deciding between agents, [Claude Code vs Codex](/en/blog/claude-code-vs-codex/ "Claude Code vs Codex") and [Codex vs Gemini CLI](/en/blog/codex-vs-gemini-cli/ "Codex vs Gemini CLI") compare them in detail. In short, Codex is a [coding agent](/en/glossary/coding-agent/ "What is a coding agent") rather than an autocomplete: you give it a task, it plans and carries it out.

## Step 1: install Codex CLI

OpenAI ships an install script for each platform, and the CLI is also on npm and Homebrew.

| Platform | Command |
| --- | --- |
| macOS, Linux | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` |
| Windows PowerShell | `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"` |
| Any platform with Node.js | `npm install -g @openai/codex` |
| macOS (Homebrew) | `brew install --cask codex` |

To update, run the same install script again, run `codex update`, or use your package manager (`brew upgrade --cask codex`). Check that it worked:

```bash
codex --version
```

## Step 2: sign in

Move into a project and start Codex:

```bash
cd my-project
codex
```

On the first run Codex asks how you want to sign in:

- **Sign in with ChatGPT:** uses your ChatGPT plan. Usage counts against your plan’s limits. This is the usual choice, and the only one that also unlocks Codex cloud.
- **API key:** uses an OpenAI API key and is billed per token. Useful for CI or when you want usage-based billing.

You can also manage this from the shell. `codex login` opens the browser sign-in, `codex login --device-auth` gives you a device code for a remote or headless machine, `codex login status` tells you whether you are signed in, and `codex logout` clears the stored credentials. To sign in with a key without typing it, pipe it in: `printenv OPENAI_API_KEY | codex login --with-api-key`.

At the time of writing, Codex is included in ChatGPT Free, Go, Plus, Pro, Business, Edu and Enterprise. Higher plans give higher limits; check [OpenAI’s Codex pricing page](https://learn.chatgpt.com/docs/pricing "Codex pricing") for current numbers. You can see where you stand any time with `/status` or `/usage` inside a session.

## Step 3: your first task

Start with something small and real so you can watch how Codex works:

```text
Explain how authentication works in this project, then add a test for
the password reset flow. Run the test suite when you're done.
```

Codex reads the relevant files, says what it plans to do, edits the code and runs the tests. A few things make this smoother:

- Type `@` to search for a file and attach it to your prompt.
- Start a line with `!` to run a shell command yourself, for example `!git status`.
- While Codex is working, press **Enter** to add instructions to the current turn, or **Tab** to queue a follow-up for after it finishes.
- Press **Esc** twice with an empty input to edit your previous message and continue from there.
- `/diff` shows what changed, including untracked files.

For screenshots or design mockups, attach images with `codex --image path/to/file.png` or paste them into the prompt.

## Step 4: approval and sandbox modes

This is the part worth understanding before you give Codex bigger jobs. Codex combines two settings: a **sandbox** that limits what commands can technically do, and an **approval policy** that decides when Codex stops to ask you.

| Mode | Flags | What Codex can do |
| --- | --- | --- |
| Auto (default) | `--sandbox workspace-write --ask-for-approval on-request` | Read, edit and run commands inside the project; asks before going outside it or using the network |
| Read only | `--sandbox read-only --ask-for-approval on-request` | Read and answer; asks before any edit or state-changing command |
| Non-interactive, read only | `--sandbox read-only --ask-for-approval never` | Never asks; useful for CI checks that should not change anything |
| Full access | `--sandbox danger-full-access` | No sandbox; only on a machine you’re willing to lose |

Inside a session, `/permissions` switches between Auto and Read Only. Network access is off by default in the workspace-write sandbox; you can turn it on in `config.toml` (see below) if your tests need it.

If Codex needs to write to a second folder, say a shared library next to your project, use `--add-dir` instead of switching to full access. OpenAI explicitly warns against `--dangerously-bypass-approvals-and-sandbox` (alias `--yolo`) outside a dedicated, isolated VM.

The sandbox is real OS-level isolation: Seatbelt on macOS, bubblewrap with seccomp on Linux and a native sandbox on Windows. Inside WSL2 Codex uses the Linux sandbox. For the wider picture of what can go wrong with agents and how to limit it, see [AI coding agent security](/en/blog/ai-coding-agent-security/ "AI coding agent security").

## Step 5: write an AGENTS.md

`AGENTS.md` is a Markdown file of instructions that Codex reads before it starts working. It’s where you put the things you would otherwise repeat in every prompt: how to build and test, code style, folders to leave alone.

Run `/init` in a session and Codex generates a first version for you. A good one is short and specific:

```markdown
# AGENTS.md

## Commands
- Install: pnpm install
- Test: pnpm test (run before saying a task is done)
- Lint: pnpm lint

## Conventions
- TypeScript strict mode, no any.
- New API routes go in src/routes and need a test.

## Don't
- Don't edit files in src/generated.
- Don't add dependencies without asking.
```

Codex looks for these files in a set order:

1. **Global:** `~/.codex/AGENTS.md` (or `AGENTS.override.md` to replace it temporarily). Use it for your personal preferences.
2. **Project:** from the git root down to the folder you’re in, Codex takes at most one file per directory, checking `AGENTS.override.md` first and then `AGENTS.md`.

The files are joined from the root down, so instructions in a subfolder come later and win over the general ones. The combined size is capped at 32 KiB by default (`project_doc_max_bytes`), which is another reason to keep them tight. Because `AGENTS.md` is a shared format, other agents read it too; [CLAUDE.md vs AGENTS.md](/en/blog/claude-md-agents-md/ "CLAUDE.md and AGENTS.md") explains how to keep one set of rules for several tools.

## Step 6: config.toml

Codex settings live in TOML files:

- `~/.codex/config.toml` for your user settings;
- `.codex/config.toml` inside a project, which Codex loads only once you’ve marked the project as trusted.

A small example:

```toml
model_reasoning_effort = "medium"
web_search = "cached"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true
```

`model` sets the default model (run `/model` in a session to see what your account offers). `model_reasoning_effort` controls how long the model thinks. `web_search` can be `cached` (the default), `live` or `disabled`; the `--search` flag turns on live search for one run.

Settings are applied in this order, highest first: command-line flags and `-c key=value`, the project config, a named profile you pick with `--profile`, your user config, and finally the system config. So `codex -c model_reasoning_effort="high"` changes effort for one run without touching your files. If you’re unsure which value won, `/debug-config` shows the layers.

## Step 7: connect MCP servers

[MCP](/en/glossary/mcp/ "What is MCP") lets Codex use outside tools: documentation search, a browser, your issue tracker, a database. Add a server with one command:

```bash
codex mcp add context7 -- npx -y @upstash/context7-mcp
```

Everything after `--` is the command that starts the server. Pass environment variables with `--env VAR=value`. For a remote server, use `codex mcp add <name> --url https://...`, and if it uses OAuth, sign in with `codex mcp login <name>`. `codex mcp list` shows what’s configured.

The same servers can be written by hand in `config.toml`:

```toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
```

Inside a session, `/mcp` lists the active servers and their tools. If you’re new to the idea, [what is an MCP server](/en/blog/what-is-mcp-server/ "What is an MCP server") is a good primer. Keep the list short: every server adds tool descriptions to the [context window](/en/glossary/context-window/ "What is a context window").

## Step 8: the commands worth knowing

Slash commands work inside a session:

| Command | What it does |
| --- | --- |
| `/init` | Generate an `AGENTS.md` for the project |
| `/model` | Pick the model and reasoning effort |
| `/permissions` | Switch between Auto and Read Only |
| `/plan` | Plan first, then implement |
| `/status`, `/usage` | Session details and remaining limits |
| `/compact` | Summarize the conversation to free up context |
| `/diff` | Show the current git diff |
| `/review` | Ask Codex to review your working tree |
| `/mcp` | List MCP servers and tools |
| `/new`, `/clear` | Start a fresh conversation |
| `/resume`, `/fork` | Continue or branch an earlier session |
| `/copy` | Copy the last answer |

And a few subcommands from the shell:

| Command | What it does |
| --- | --- |
| `codex exec "..."` | Run a task without the interactive UI, for scripts and CI |
| `codex review --uncommitted` | Review uncommitted changes (also `--base <branch>` or `--commit <sha>`) |
| `codex resume` | Pick a recent session to continue |
| `codex fork --last` | Branch the most recent session |
| `codex -C path/to/dir` | Start in a different folder |
| `codex doctor` | Check your installation |

`codex exec` is the one to remember for automation. It prints the result and exits, accepts `--json` for machine-readable output and `--output-last-message` to save the final answer to a file. In CI, pair it with a sandbox, for example `codex exec --sandbox workspace-write "fix the failing lint errors"`.

## Step 9: resume and fork sessions

Codex stores your conversations locally, so closing the terminal doesn’t lose work:

- `codex resume` opens a picker of earlier sessions.
- `codex resume --last` jumps straight into the latest one from the current folder; add `--all` to look across every folder.
- `codex fork` (or `/fork` in a session) copies a conversation into a new one, so you can try a different approach without losing the original.
- For non-interactive runs, `codex exec resume --last` continues the last `exec` session.

Forking is handy when Codex has built up good context on a problem and you want to try two solutions from the same starting point.

## Tips for better results

- **Commit before and after.** OpenAI’s own advice is to make a git checkpoint before a task and after it. If a change goes wrong, `git restore` is faster than arguing with the agent.
- **Say how to verify.** “Run `pnpm test` and fix failures” gets better results than “make it work”.
- **Plan bigger changes.** Use `/plan` for anything that touches more than a couple of files, and read the plan before Codex starts editing.
- **One task per conversation.** Start fresh with `/new` between unrelated tasks; old context costs tokens and confuses the model.
- **Compact long sessions.** `/compact` keeps the important parts and drops the rest.
- **Use a worktree for parallel work.** Two agents in the same folder will overwrite each other. [Git worktrees](/en/blog/git-worktree-parallel-agents/ "Git worktrees for parallel agents") give each one its own copy.

## When one terminal isn’t enough

Once Codex is part of your day, you’ll want more than one session running: one fixing a bug, another writing tests, maybe a second account when the first hits its limit. That’s where a single terminal gets awkward.

AgentVera is a desktop app for macOS, Windows and Linux that runs Codex (and other CLI agents) in real terminals, side by side. It uses the Codex login you already have. See the [Codex in AgentVera](/en/agents/codex/ "Codex in AgentVera") page for details.

- **[Workspace](/en/features/workspace/ "Workspace"):** a grid of agents per project, from 1×1 to 5×4. Pick the model and effort per agent; the list is read live from Codex. Agents pick up their conversation again after a relaunch.
- **Permissions per agent:** choose Ask, Auto or Full access when you create an agent, instead of remembering flags.
- **Worktrees:** create a worktree from the [Git panel](/en/features/git-and-github/ "Git and GitHub") and start an agent in it with one click.
- **[Account switching](/en/features/account-switching/ "Account switching"):** each Codex account gets its own home folder, remaining limits show in the status bar, and on Pro and Team an account chain moves on to the next account when the 5-hour or weekly limit runs out.
- **[MCP manager](/en/features/mcp-manager/ "MCP manager"):** set up MCP servers once; they attach to Codex on every launch.
- **[Code review](/en/features/code-review/ "Code review"):** have another agent review what Codex changed before you merge.

The grid, worktrees, code review and the MCP manager are on the free plan. [Download AgentVera](/en/download/ "Download AgentVera") and try it on your own repo.

## Wrapping up

Install Codex, run `codex`, sign in with ChatGPT and start with a small, real task. Leave it in Auto mode and switch to read-only with `/permissions` when you only want answers. Put your project rules in `AGENTS.md`, your defaults in `config.toml`, and add MCP servers only when you need them. Commit before and after each task, and use `codex resume` to pick up where you left off. If you also want to try Google’s agent, read [how to use Gemini CLI](/en/blog/how-to-use-gemini-cli/ "How to use Gemini CLI").

## Frequently asked questions

**Is Codex CLI free?** The CLI itself costs nothing to install. To use it you sign in with a ChatGPT account or an OpenAI API key. At the time of writing (October 2026), Codex is included in ChatGPT Free, Go, Plus, Pro, Business, Edu and Enterprise, with usage limits that grow with the plan. API keys are billed per token.

**Does Codex CLI work on Windows?** Yes. Install it from PowerShell with the official script or with npm. On Windows, Codex uses its own sandbox, and inside WSL2 it uses the Linux sandbox. Approval modes, AGENTS.md and config.toml work the same on every platform.

**How do I stop Codex from changing files?** Run /permissions and choose Read Only, or start Codex with --sandbox read-only. Codex can then read files and answer questions, but it asks before editing anything or running commands that change state.

**Where does Codex CLI keep its settings?** User settings live in ~/.codex/config.toml. A project can add its own .codex/config.toml, which Codex loads only for trusted projects. Command-line flags and -c key=value override both for a single run.

**How do I continue an earlier Codex session?** Run codex resume to pick from a list of recent sessions, or codex resume --last to jump straight into the most recent one in the current folder. Inside a session, /resume does the same and /fork starts a new branch from the current conversation.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/