You have decided to try Codex CLI, and the question is not how to install it, because that is three commands: it is how to do the first task without ending up with a diff you do not understand and cannot undo. The official documentation, read on November 13, 2026, gives the minimal sequence: install the CLI, open a project folder, run codex and choose "Sign in with ChatGPT" (or another available method), then describe a task and create Git checkpoints before and after, so you can go back. The rest of this page is the discipline that turns that sequence into work you can verify: a small task with an executable criterion for "done", a perimeter of files declared beforehand, and a check of your own, not the agent's, on what has changed. The cost is time: it is slower than "you do everything yourself", and it pays off only when the task is small enough to be checked in a few minutes.
Method and limits. I am not affiliated with OpenAI. I did not install or launch Codex CLI and I did not call any model: the installation commands and the commands inside Codex I report from the official documentation, read on 2026-11-13, and I did not try them. What I did run myself, twice with the same output, is the perimeter-check script you will find below: it runs on a test repository built on the spot (Python 3.14, Git 2.53, Node 24), without any assistant.
Before installing: two decisions
How you sign in. With a ChatGPT account or with an API key. Part 1 of the series compares the two methods; here it is enough to know that you can change later, with codex login, which by default opens the browser for ChatGPT sign-in and also accepts an API key or an access token.
On which system. The sandbox page says that on macOS the sandbox works right away, because it uses Seatbelt, which is already built in. On Linux and WSL2 you first have to install bubblewrap with the package manager (the page shows sudo apt install bubblewrap for Ubuntu and Debian): Codex uses the first bwrap it finds in the PATH and, if there is none, falls back to a bundled helper program, which however requires the creation of unprivileged user namespaces. On Windows from PowerShell it uses a native sandbox, and in WSL2 the Linux one; the page on approvals and security specifies that WSL1 was supported up to version 0.114 and that from 0.115 the Linux sandbox switched to bwrap, so WSL1 is no longer supported. If the sandbox does not start, Codex shows a warning at startup: the symptom is there, not in some mysterious freeze of your editor.
Installation: four routes, one program
The commands below are copied from the Codex CLI page of the documentation. I did not run them, and for that reason there is no output to show: they are the vendor's scheme, to be adapted to your system. To update, the page says to run the same command again (for Homebrew brew upgrade --cask codex); there is also codex update, which according to the commands page works only when the installed release supports automatic updating.
# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Windows (from a new PowerShell window)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
# npm, on any system
npm install -g @openai/codex
# Homebrew
brew install --cask codex
The choice among the routes is one of governance, not of technique. The lines with curl ... | sh and irm ... | iex run what they download at the moment they download it: in a regulated environment, download the script first and read it, or use a package manager that your security department already checks. npm relies on Node and fits with your version tools; Homebrew is the tidiest route on macOS. Whichever you choose, note the installed version: in part 1 I showed with a script that the CLI releases alpha versions at an almost daily pace, and two colleagues may see different commands.
The first launch, and why the Git repository matters
At launch, the security page explains that Codex detects whether the folder is under version control and proposes a different starting value: in folders with Git it recommends the Auto profile (write in the workspace plus approvals on request), in the others it recommends read-only; depending on the configuration it may also start in read-only until you declare the folder trusted. It is a good practical reason to work inside a repository: without Git the agent starts from a more restrictive profile, and you have no tool to see what it has changed. The three opening commands are these, in order.
cd ~/projects/price-list
git status # the working tree must be clean
git log -1 --oneline
codex # on first launch: "Sign in with ChatGPT" or another method
A clean git status is not formalism. With an already dirty tree you can no longer tell what the agent changed from what you had changed, and your only safety net, the comparison with the last commit, loses its meaning. The CLI page says it in one line ("Create Git checkpoints before and after a task so you can revert changes"): the checkpoint before is a commit, the one after is the commit you make only after checking.
The first task: four parts, one of them executable
The Best practices page of the documentation suggests including four things in the prompt: the goal, the context (which files, folders or errors matter), the constraints (which standards or conventions to respect) and the "done when", that is, what must be true for the task to be finished, for example tests that pass or a bug that no longer reproduces. A typical first-day prompt, written by me as an example to adapt to your stack, puts in the "done when" a command that you yourself can run again.
Add a test for the calcolaSconto function in src/prezzi.js.
Cover: zero amount, negative amount (must throw RangeError), 100% discount.
Do not modify other files. Follow the style of the tests already in the repository.
You are done when "node --test src/prezzi.test.js" exits with code 0.
The prompt is a text, not a program, and I gave it to no agent: it is a scheme to adapt, not run. Notice, though, that the last two lines are verifiable by a machine: "do not modify other files" is a perimeter, "exits with code 0" is a criterion. The agent reads them as instructions, you can turn them into a check that does not depend on the agent. A goal like "improve this project" does not have this property: no command can tell you whether it has been reached.
The check that stays yours: perimeter and criterion
The script that follows builds a test repository in a temporary folder, with a calcolaSconto function and a starting commit. Then it simulates two changes, written in the script itself (there is no assistant): in the first only the requested test file is created; in the second, in addition, the README.md is modified, a file that the task did not authorize. The giudica function asks the two questions of the first task: do the touched files lie within the PERIMETRO set? and does the CRITERIO command exit with code 0? For the first it reads git status --porcelain -uall (the -uall option also lists the individual new files, not just the folder); for the second it launches node --test with the tap reporter, and from the output keeps only the pass and fail lines: the timings, which change at every run, stay out, and for that reason the reported output is identical at every run.
The function names and file names in the listing (giudica is "judges", PERIMETRO the perimeter, CRITERIO the criterion, calcolaSconto "calculate discount", prezzi "prices") are Italian identifiers that I left unchanged; the printed texts and the comments are in English.
"""The check that stays yours even if you use an agent: what changed, and where.
Builds a test repository, simulates two "agent changes" (written here,
no assistant involved) and judges them with the two questions of the first task:
are the touched files inside the declared perimeter? does the command of the done-criterion pass?
"""
import subprocess, sys, tempfile
from pathlib import Path
PERIMETRO = {"src/prezzi.test.js"} # the only files the task may touch
CRITERIO = ["node", "--test", "--test-reporter=tap", "src/prezzi.test.js"]
def git(repo, *args):
return subprocess.run(["git", *args], cwd=repo, check=True,
capture_output=True, text=True).stdout
def prepara(repo):
git(repo, "init", "-q")
git(repo, "config", "user.email", "prova@example.org")
git(repo, "config", "user.name", "Test")
(repo / "src").mkdir()
(repo / "src/prezzi.js").write_text(
"export function calcolaSconto(importo, percento) {\n"
" if (importo < 0) throw new RangeError('negative amount');\n"
" return importo - importo * percento / 100;\n}\n")
(repo / "package.json").write_text('{"type": "module"}\n')
(repo / "README.md").write_text("Price list\n")
git(repo, "add", "-A")
git(repo, "commit", "-q", "-m", "starting state")
TEST = (
"import test from 'node:test';\nimport assert from 'node:assert/strict';\n"
"import { calcolaSconto } from './prezzi.js';\n"
"test('zero amount', () => assert.equal(calcolaSconto(0, 10), 0));\n"
"test('negative amount', () => assert.throws(() => calcolaSconto(-1, 10), RangeError));\n"
"test('100% discount', () => assert.equal(calcolaSconto(80, 100), 0));\n")
def giudica(repo):
righe = git(repo, "status", "--porcelain", "-uall").splitlines()
toccati = sorted(r[3:] for r in righe)
fuori = [f for f in toccati if f not in PERIMETRO]
prova = subprocess.run(CRITERIO, cwd=repo, capture_output=True, text=True)
esiti = {l.lstrip("# ") for l in prova.stdout.splitlines()
if l.startswith(("# pass", "# fail"))}
print(" touched :", ", ".join(toccati))
print(" outside :", ", ".join(fuori) or "none")
print(" criterion:", "passes" if prova.returncode == 0 else "FAILS", sorted(esiti))
return not fuori and prova.returncode == 0
if __name__ == "__main__":
with tempfile.TemporaryDirectory() as cartella:
repo = Path(cartella)
prepara(repo)
(repo / "src/prezzi.test.js").write_text(TEST)
print("A) change inside the perimeter")
ok_a = giudica(repo)
(repo / "README.md").write_text("Price list\nDiscounts coming soon\n")
print("B) the same change, plus a file nobody asked for")
ok_b = giudica(repo)
git(repo, "restore", "README.md")
print("C) after git restore README.md")
ok_c = giudica(repo)
print("verdicts:", ok_a, ok_b, ok_c)
sys.exit(0 if (ok_a, ok_b, ok_c) == (True, False, True) else 1)
# Command: python3 -I perimetro.py
# Output:
# A) change inside the perimeter
# touched : src/prezzi.test.js
# outside : none
# criterion: passes ['fail 0', 'pass 3']
# B) the same change, plus a file nobody asked for
# touched : README.md, src/prezzi.test.js
# outside : README.md
# criterion: passes ['fail 0', 'pass 3']
# C) after git restore README.md
# touched : src/prezzi.test.js
# outside : none
# criterion: passes ['fail 0', 'pass 3']
# verdicts: True False True
Read the three scenarios. In case A the touched files are all inside the perimeter and the three tests pass: it is the outcome you want. In case B the criterion still passes (three tests, zero failures), but the perimeter is violated by README.md: the green test alone is not enough, and it is exactly the kind of extra change that a summary written by the agent may fail to mention. In case C, after git restore README.md, the repository goes back to case A. The script proves nothing about Codex: it proves that the comparison between what you asked and what changed is a mechanical check that you can run yourself, in ten lines, before reading a single line of diff.
When not to use it like this: the fixed-list perimeter works for small and predictable tasks, such as adding a test. For a refactoring that by its nature touches many files, a perimeter by folder or by pattern (for example "only under src/prezzi/") makes more sense, and the task should perhaps be split.
The inner commands you need right away
The CLI commands page documents dozens of commands inside the session; for the first day six are enough, which I verified one by one on that page.
/init: generates a draftAGENTS.mdin the current folder, to be reviewed and edited (part 4 explains how to write it well)./status: shows the active model, the approval policy, the writable folders and the token consumption of the session./permissions: opens the selector of approval profiles, for exampleAutoorRead Only./model: changes the model and the reasoning level (part 5)./review: reviews the working copy and summarizes the problems found, looking mainly at behavior changes and missing tests./diff: shows the exact changes to the files, to be used after the review.
The command that matters most is /status, to be opened at the start of every task you care about: it tells you with which permissions and which writable folders you are working. Many incidents with this kind of tool start from a broad permission granted for one activity and forgotten for the next. /review is useful as a second pair of eyes but remains another pass of the same tool: it replaces neither your git diff nor your criterion of "done". There is also the non-interactive form codex review, with a single target among --uncommitted, --base and --commit, or a custom prompt.
The command-line options that change the work
Besides the interactive session, the CLI page lists these features, which I report here with what they imply.
codex resume: reopens a recent chat;--lastrefers to the current folder, unless you add--all.codex --image: attaches a screenshot or a diagram to the first prompt.codex --search: moves web search from "cached", which is the default, to live browsing.codex cloud: browses and sends work to Codex Cloud, then applies the results to the local repository (part 7).codex mcp: adds local or remote MCP servers and shows their tools.codex exec: non-interactive execution for scripts and CI (part 6).
The difference between "cached" and "live" search has a security reason. The security page explains that the default mode serves results from an index of web pages maintained by OpenAI, instead of downloading pages in real time, and that this reduces exposure to prompt injection from arbitrary content; with --search (or web_search = "live") you get recent data but you accept that risk. Use it when the task depends on a library released recently, and treat web results as untrusted, as the same page says. If you do not need it, leave it off.
When something goes wrong
- The login does not complete. Run
codex loginagain and follow the flow in the browser; if your plan does not include the surface you are trying, the pricing page is the first to reread. - The sandbox does not start on Linux. Check that
bwrapis installed and that unprivileged user namespaces are allowed; the sandbox page has a section dedicated to Ubuntu 24.04 and to the AppArmor profile ofbwrap. - The agent keeps asking for permission. It is the prudent behavior. Do not solve it by raising permissions at random: part 3 shows how to widen only what is needed.
- The behavior does not match a guide. Look at the version you installed and compare it with the releases. The commands page documents
codex doctor, which generates a local diagnostic report on installation, configuration, authentication, runtime environment, Git and terminal; it is the tool to use before opening a report.
In all four cases the rule is the same: first you read the message, then you narrow the task, and only last do you widen the permissions. Raising permissions is the last resort, because it is the only one of the four that makes a later mistake more serious.
Frequently asked questions
Do I have to work inside a Git repository to use Codex?
It is not mandatory, but it is recommended by the documentation. In folders without version control Codex recommends the read-only profile, and you would not have the comparison with the last commit to see what has changed. For an experiment, create a test repository: git init and one commit are enough.
How do I go back if the agent ruins a file?
With the checkpoint made beforehand. If the file is not yet in a commit of yours, git restore <file> brings the file back to the last commit, as scenario C of the script shows; if you have already committed, git revert undoes the commit with a new commit. That is why it is convenient to commit the agent's changes separately from your own.
How do I update the CLI?
By running again the same command you installed it with, according to the CLI page; with Homebrew you use brew upgrade --cask codex. After the update open a new session: guides written for earlier versions may describe commands that have changed.
What you can do now
You can install the CLI for your system and understand what you need first (bwrap on Linux, a Git repository everywhere), formulate a task with goal, context, constraints and criterion, and check yourself, with a mechanical check, that the changes stay within the perimeter and that the criterion passes. The next step is to understand what the agent can do while it works: in part 3 on sandbox and approvals you see the two knobs that decide it. If you are missing the product map, go back to part 1.
What I did not verify
I did not install or run the CLI: the names of the commands, of the options and of the inner commands are verified on the documentation of 2026-11-13, not on a machine. I did not verify the behavior of the sandbox on Linux, macOS or Windows, nor the exact text of the startup warnings. The example prompt and the perimeter check are mine, not the vendor's; the check does not prove that Codex respects the perimeter, only that you can verify it.
The same series also includes choosing the model and the reasoning level (part 5) and the comparison with Claude Code, Copilot and Cursor (part 8).
Sources
- Codex CLI - the four installation routes, the first launch, the Git checkpoints, the
resume,--image,--search,cloud,mcp,execfeatures; consulted on 2026-11-13 - Developer commands -
/init,/status,/permissions,/review,/diff,codex doctor,codex login,codex update,codex review; consulted on 2026-11-13 - Sandbox - requirements by operating system,
bubblewrap, startup warnings; consulted on 2026-11-13 - Agent approvals & security - recommended profile with or without Git, "cached" and "live" web search, end of WSL1 support; consulted on 2026-11-13
- Best practices - the four parts of the prompt: Goal, Context, Constraints, Done when; consulted on 2026-11-13
The perimetro.py script was run twice with Python 3.14, Git 2.53 and Node 24, with the same output; the Codex CLI was not installed or run, and the installation commands are reported as the vendor's scheme.
Commenti
Caricamento commenti...
Sign in to comment