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

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 and Codex vs Gemini CLI compare them in detail. In short, Codex 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.

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

codex --version

Step 2: sign in

Move into a project and start Codex:

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 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:

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.

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.

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:

# 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 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:

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 lets Codex use outside tools: documentation search, a browser, your issue tracker, a database. Add a server with one command:

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:

[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 is a good primer. Keep the list short: every server adds tool descriptions to the context window.

Step 8: the commands worth knowing

Slash commands work inside a session:

And a few subcommands from the shell:

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 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 page for details.

• 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 and start an agent in it with one click.
• 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: set up MCP servers once; they attach to Codex on every launch.
• 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 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.