Codex CLI: Install, Start and Check Your First Task
Install OpenAI Codex CLI, start a bounded task, inspect its changes and save a repeatable result. A practical first-run checklist with troubleshooting steps.
Last updated: 2026-09-18
A successful installation and a successful task are two separate checks. This guide takes you from the codex command to one small result you can inspect, then repeat. It is an independent Codex Pulse guide, checked against OpenAI documentation on September 18, 2026.
Install Codex CLI
If you already use npm, OpenAI documents this installation command:
npm install -g @openai/codex
On macOS, Homebrew is another documented option:
brew install --cask codex
Choose one installation method. See the official Codex CLI page for standalone installers, platform instructions and current update commands. Do not install multiple copies to troubleshoot a missing command without first checking which installation your terminal finds.
Update the installation you use
For an npm installation, run npm install -g @openai/codex again. For Homebrew, run brew upgrade --cask codex. These are the update commands in the official CLI guide. Keep your installation method consistent, then repeat one saved task after the update.
Start in the intended project
Open a terminal in the project directory and run:
codex
The first run offers sign-in with ChatGPT or another available authentication method. Follow the official authentication documentation for your account. Codex Pulse does not need your password, API key or session token.
Before requesting edits, inspect your working tree and preserve any existing work. For a Git project, git status --short helps identify changes that predate the task. Start with a small, non-sensitive repository or a disposable copy if you are still learning the workflow.
Give the first task an observable finish
Try an explanation task before a broad rewrite:
Find the code that handles one user-visible behavior in this project.
Explain the entry point, the important function and the existing test.
Include file paths. Do not change files.
Replace “one user-visible behavior” with something concrete, such as changing a profile name. Then open the cited files and check whether the explanation follows the actual code. An answer that sounds plausible but points at the wrong handler has failed this task.
For the first edit, choose a small behavior change and name its acceptance check:
Make the requested behavior change in the supplied example.
Preserve unrelated changes. Run the relevant existing check.
Report what changed, the actual check result and any unfinished work.
Supply the behavior and the check rather than leaving them implicit. The cost of a bounded exercise is that it proves less about a large project; the benefit is that you can inspect the whole result.
Review the result before continuing
| Check | What to inspect | A useful failure signal |
|---|---|---|
| Scope | Changed files and diff | Unrelated files changed |
| Behavior | The acceptance case | The original failure still occurs |
| Verification | Actual command output | A success claim without a completed check |
| Completion | Remaining requested work | The agent stopped before the task was finished |
For Git projects, inspect git diff yourself. Separate a failed test from a test that could not run because a dependency or service was unavailable. Keep the original output and a short note about any follow-up you supplied.
If the first run fails
The terminal cannot find codex: check the installation result and restart the terminal after following the installer's instructions. Confirm that you are using the shell where the command was installed. Use the official instructions for that installation method rather than guessing another package name.
Sign-in fails: preserve the exact error and use the official authentication guidance. Do not publish browser callback URLs or tokens in an issue report.
A tool cannot run: inspect the named command and its error. A missing dependency, unavailable service or denied permission is a distinct observation from an incorrect generated answer. Preserve your permission boundaries while investigating it.
The task feels slow or stops early: use the Codex quality and latency checklist. Record what remained incomplete and where the time was spent.
Save one repeatable result
Once the basic workflow works, record the task, requested model, effort, client version, original output and checks. The repeatable benchmark guide explains how to keep conditions comparable.
If you want a small visual exercise, start with the pelican prompt and examples. A drawing lets you inspect a concrete artifact; it does not certify software-engineering ability. The next useful checkpoint is the same task repeated from the same starting state.