Get started with OpenAI Codex CLI: install it and make your first change safely

Codex CLI is OpenAI's coding agent for the terminal. You describe a change in plain English and it reads your project, edits files and runs commands to get there. This recipe takes you from install to a first small edit, with the safety settings explained as we go.

Before you start

A computer with a terminal.
A way to sign in: a ChatGPT account on a plan that includes Codex, or an OpenAI API key (see Step 3). OpenAI's pricing page lists which plans include Codex and changes from time to time, so check it rather than relying on this page. See our OpenAI Codex page for a summary.
A practice folder you don't mind changing.

Step 1: Install it

OpenAI's docs list four ways. Pick one:

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

The macOS/Linux and Windows commands are also how you update later. With npm, run the install command again. With Homebrew, run brew upgrade --cask codex.

Step 2: Make a practice project

mkdir codex-practice
cd codex-practice
git init
echo "<h1>Hello</h1>" > index.html
git add .
git commit -m "Starting point"

The git lines give you an undo button. Codex works best inside a Git folder, and OpenAI's docs recommend its default mode for version-controlled folders. More in our git safety net guide.

Always start Codex from the folder you want it to work in:

codex

The first time, choose Sign in with ChatGPT (or another sign-in method if one is offered). OpenAI's README recommends ChatGPT sign-in for people on a plan that includes Codex.

If you'd rather use an API key, the docs show this way of passing it in without typing it into your shell history:

printenv OPENAI_API_KEY | codex login --with-api-key

API key usage is billed at OpenAI's API rates, and the pricing page says it doesn't include cloud-based features such as GitHub code review. To see how you're signed in, run codex login status. To sign out, run codex logout.

Keep your API key private. Never paste it into a chat, commit it to Git or share a screenshot of it.

Step 4: Understand approvals and the sandbox

Two settings decide how much Codex can do without asking:

Sandbox mode limits what commands can touch. The three values are read-only, workspace-write and danger-full-access.
Approval policy decides when Codex stops to ask you. Common values are on-request and never.

The usual starting point is the Auto preset, which OpenAI describes as --sandbox workspace-write --ask-for-approval on-request. In that mode Codex can read files, make edits and run commands inside your working folder on its own. It asks first if it wants to edit files outside the workspace or run a command that needs network access. By default, network access is off.

You can set these when you start Codex:

# Look but don't touch: good for a first exploration
codex --sandbox read-only --ask-for-approval on-request

# The Auto preset
codex --sandbox workspace-write --ask-for-approval on-request

Inside a session, /permissions lets you change when Codex can edit files or run commands without asking, and shows the active sandbox. OpenAI's docs suggest switching to read-only with it when you just want to chat or plan.

One flag to avoid as a beginner: --dangerously-bypass-approvals-and-sandbox (alias --yolo) switches off both the sandbox and approvals. OpenAI's docs mark it as not recommended.

Step 5: Ask a question first

Start with something that only reads:

What files are in this project and what does index.html do?

Step 6: Make your first change

Turn index.html into a simple page with a title, a short paragraph about my favourite hobby and some basic styling. Keep it in one file.

Read what Codex proposes, and any approval request, before saying yes. Then open index.html in your browser and ask for tweaks:

Make the heading blue and centre everything.

Check what changed with Git:

git status
git diff

If you don't like it, git restore index.html puts the file back the way you committed it. If you like it, commit it.

Step 7: Give it standing instructions

Codex reads a plain Markdown file called AGENTS.md for project instructions, such as how to run tests or which style to follow. Our AGENTS.md explainer shows how to write one.

Step 8: Useful commands

Anything starting with / is a command. Three that are worth knowing now, from OpenAI's docs:

Command	What it does
`/permissions`	Choose when Codex can edit files or run commands without asking, and check the active sandbox
`/mcp`	Lists configured MCP tools, so you can see which outside tools Codex can call
`/skills`	Lists skills you can use (the docs say you can also type `$` to mention one)

To plug in outside tools, see Connect Codex to MCP servers.

Safety habits

Commit before big changes so you can undo.
Read before approving anything that deletes files, installs software or needs the network.
Start in read-only when you're exploring a project you don't know.
Keep secrets out of prompts and files.

Troubleshooting

"command not found: codex". Open a new terminal window so your shell picks up the install. If it persists, run the install command again.

Codex keeps asking for permission. That's the approval policy working as designed. Check /permissions to see what is active before loosening anything.

Sign-in doesn't work. Run codex login status to see what Codex thinks you are signed in with, and check OpenAI's pricing page to confirm your plan includes Codex.

Where to go next

Compare with another terminal agent in Install Claude Code and make your first change.
Learn what an MCP server is.