Field guide / 10 min
Install Codex and prove the toolchain
Start with a known binary, a visible version, and diagnostics you can repeat.
A reliable Codex workflow starts before the first prompt. Install from the official standalone script, identify the binary you are actually running, update deliberately, and use the built-in diagnostic report instead of guessing about configuration, authentication, Git, or terminal failures.
Verified terminal sequence
- $
curl -fsSL https://chatgpt.com/codex/install.sh | sh - $
irm https://chatgpt.com/codex/install.ps1 | iex - $
codex --version - $
codex update - $
codex doctor
Working principles
Identify the executable
Shell aliases and multiple install methods can point at different binaries. Record the resolved command and version before debugging behavior.
Update intentionally
Use codex update only when the installed release supports self-update. Review release-sensitive behavior after an update rather than assuming every flag stayed identical.
Diagnose by layer
codex doctor inventories installation, config, auth, runtime, Git, terminal, app-server, and threads so setup failures become evidence instead of folklore.
Field procedure
- 01
Install from the official script
Use install.sh from a POSIX shell on macOS/Linux, or install.ps1 through PowerShell on Windows. Keep first-time setup interactive so path and shell changes stay visible.
- 02
Confirm the active version
Run codex --version from the same shell and repository context you plan to use for work.
- 03
Check command discovery
If the shell cannot find Codex, reopen the terminal and inspect PATH before installing a second copy.
- 04
Generate a diagnostic report
Run codex doctor and read each layer. Fix the first failing dependency rather than changing unrelated settings.
- 05
Capture a baseline
Record the version and successful diagnostic result in your local setup notes so later regressions have a comparison point.
PASS / FAIL
Acceptance checklist
- The installer matches the active shell and operating system.
- codex --version succeeds.
- codex doctor reports the intended runtime and repository.
- Only one expected Codex binary wins on PATH.
- No credential or diagnostic file is committed.
WATCH / REJECT
Failure patterns
- Running the PowerShell installer in a POSIX shell, or the shell installer in PowerShell.
- Installing repeatedly before checking PATH.
- Treating self-update support as universal.
- Publishing diagnostic output before reviewing it for sensitive paths.