Install and Update Codex CLI Before Your First Real Task

The easiest way to misjudge Codex CLI is to mix three decisions together on day one:

• how you install it
• how you sign in
• which operating surface you are actually using on Windows

When those get mixed, the first failure becomes impossible to read.

A bad PATH decision looks like a Codex problem. A browser-login problem looks like a product problem. Choosing the wrong Windows surface looks like a model problem.

This page is for separating those layers before you hand Codex a real repository.

Start With The Smallest Sane Setup Path#

If you want the practical default and you are not doing anything unusual, start here:

• macOS or Linux personal machine: install with npm and sign in with ChatGPT
• Windows 11 personal machine: install Codex and use the native Windows sandbox first
• Windows machine where your repo and tooling already live in Linux: use WSL2 on purpose
• CI or programmatic workflow: use API key auth instead of ChatGPT sign-in

That may sound boring. It is supposed to. The first win is not a clever setup. The first win is a stable shell surface that does not distort your first repo task.

Pick The Login Lane Before You Install Anything#

OpenAI currently supports two main login paths in Codex:

• Sign in with ChatGPT for subscription access
• Sign in with an API key for usage-based access

That sounds like a small choice, but it changes billing and workflow expectations.

Choose Sign in with ChatGPT when:

• you already have a ChatGPT plan that includes Codex
• you want the standard local developer experience
• you are evaluating Codex as a day-to-day coding tool rather than as automation infrastructure

Choose API key when:

• you want usage-based billing through the OpenAI Platform account
• you are wiring Codex into programmatic or CI-style flows
• you want the CLI on a machine where subscription-style desktop use is not the point

One detail worth knowing up front: the authentication page says the CLI defaults to ChatGPT sign-in when no valid session exists. It also says some features tied to ChatGPT credits are available only with ChatGPT login.

If this is your laptop or daily dev machine and you are just trying to get to a first real coding task, start with ChatGPT sign-in. It removes one whole layer of API-billing and key-management noise from the first run.

Install Codex CLI From One Channel And Stay In That Channel#

The current OpenAI CLI docs foreground npm. The official openai/codex repository also documents Homebrew and GitHub release binaries.

For most developers, npm should still be the default first path because it is the shortest route from install to update, and the official CLI docs publish the matching npm upgrade command as well.

macOS Or Linux: Start With npm Unless Your Team Already Standardized Elsewhere#

npm i -g @openai/codex
codex

On first launch, Codex should open its terminal UI and prompt you to authenticate with either your ChatGPT account or an API key.

If your team already manages CLI tools through Homebrew, the official repo also lists:

brew install --cask codex
codex

If you prefer a direct binary, the openai/codex repository points to the latest GitHub release and the platform-specific archives.

The practical rule is simple: choose one channel and keep updates in that same channel. A surprising amount of Codex setup pain is just PATH confusion created by mixing npm, Homebrew, and manual binaries on the same machine.

If You Are On Windows, Decide Between Native And WSL2 First#

This is the setup choice that now causes the most avoidable confusion because older advice and current advice do not say the same thing.

The current Windows docs now recommend the native Windows sandbox by default. WSL2 is still the right choice when you want a Linux-native environment or your real repos and tooling already live there.

That means the decision is no longer "Windows equals WSL2."

It is:

• use native Windows first when this is a normal Windows developer machine
• use WSL2 when your real workflow is already Linux-shaped

If your repo, package managers, and shell habits already live in WSL2, do not force a native install out of habit. Start where the work already lives.

The WSL2 setup flow still starts with:

wsl --install
wsl

Then, from the WSL shell:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install 22
npm i -g @openai/codex
codex

The Windows docs also make one operational point that matters later: if you do use WSL2, keep your repositories inside the Linux home directory such as ~/code/my-app, not in Windows-mounted paths like /mnt/c/..., if you want better I/O and fewer permission surprises.

If you already know the team is staying native on Windows, do that on purpose and treat native sandbox behavior as the real starting point. Do not assume the native path and the WSL2 path behave the same just because both can launch the CLI.

What A Healthy First Run Actually Proves#

Your first successful run does not need a real repo yet.

It only needs to prove four boring things:

• the shell resolves codex to the binary you meant to install
• the CLI launches cleanly instead of failing at process start
• the login path you chose actually works on this machine
• restarting codex does not immediately dump you back into auth confusion

One simple check is better than jumping straight into production code: create a scratch directory, launch codex, and ask it to describe the current directory and stop before editing anything.

If that tiny loop already feels unstable, your repo trial will not magically be cleaner.

The authentication docs say Codex caches login details locally and reuses them on the next CLI start. They also note that the CLI and IDE extension share the same cached login details.

That is useful, but it comes with one security detail: if Codex stores credentials in ~/.codex/auth.json, treat that file like a password. Do not commit it, paste it into tickets, or drop it into a repository sync path without thinking.

If Browser Login Fails, Do Not Guess#

When login breaks, most people waste time on the wrong layer.

The auth docs call out two common cases for ChatGPT sign-in trouble:

• you are in a remote or headless environment
• your local networking blocks the localhost callback that returns the token to the CLI

In that case, the official fallback is device-code authentication:

codex login --device-auth

The same auth page also says direct codex login runs produce a dedicated codex-login.log file under your configured log directory. Use that log when the browser flow or device-code flow fails instead of repeatedly retrying blind.

If you are signing in on a machine with no browser at all, the official docs also describe a trusted-machine fallback where you authenticate locally, then copy the cached auth file to the headless machine. That is useful for controlled environments, but it should be treated like secret handling, not like a casual file copy trick.

If you are in WSL and the shell still says codex cannot be found, the Windows guide suggests checking the binary on PATH before you do anything else:

which codex || echo "codex not found"

Do One Environment Reality Check Before You Blame Codex#

Codex CLI is not just "install package, paste prompt, done."

The approvals and security docs still matter on day one because the default execution model changes what the agent can actually do. The default workspace-write sandbox keeps network access off unless you explicitly allow it, and approval policy plus sandbox mode change which reads, edits, and commands are allowed.

That means many bad first impressions are really expectation mismatches:

• the task needs internet access
• the task expects package installation
• the task expects edits outside the workspace
• the task assumes Codex can run commands you have not allowed it to run

If your first task is one bounded repo change, you can usually avoid most of that noise.

If your first task depends on external systems, package installs, or cross-workspace edits, learn the approval and sandbox defaults before you call the workflow disappointing.

Update Codex Without Changing Lanes Midway#

The current official CLI page gives a direct npm upgrade command:

npm i -g @openai/codex@latest

Before you update, check the Codex changelog so you know whether you are absorbing a small fix, a workflow change, or a platform-specific behavior shift.

If you installed Codex with Homebrew or a release binary, update through that same channel instead of layering npm on top of it later. The goal is not just to "have the newest version." The goal is to know which binary your shell is actually launching.

After an update, reopen codex before you touch a real repository. If the shell is launching the wrong binary, it is much cheaper to find that out in an empty directory than in the middle of an agent run.

Switching From API Key To ChatGPT Login#

This is the migration that trips people most often after they start hearing about subscription access.

The OpenAI help center says that if you previously used the Codex CLI via API key and want to move to subscription-based access, you should:

1. update Codex using your preferred package manager
2. run codex logout
3. run codex again and sign in with ChatGPT

That sequence matters because it clears old assumptions instead of leaving you to guess which credentials the CLI is still using.

Leave Setup Only After These Checks Pass#

Before you move into a real repo, make sure all five of these are true:

1. codex launches cleanly from the shell you actually use for work
2. you know whether you are on native Windows or WSL2, and that choice was deliberate
3. you know whether this machine is using ChatGPT sign-in or API key access
4. you know whether your next task will need sandbox, approval, or network changes
5. you have not scattered Codex across multiple install channels on the same machine

Once those are true, the next tutorial becomes meaningful because you are finally testing workflow instead of setup.

Official References#

• Codex CLI
• Authentication
• Agent approvals and security
• Windows
• Using Codex with your ChatGPT plan
• openai/codex repository

What To Read Next#

Read Use Codex CLI on One Real Repo Task Without Turning It Into a Broad Rewrite once the shell, login path, and Windows-versus-WSL2 decision are settled.

Read Use the Codex App to Hand Off One Bounded Coding Task and Review the Result if you want the same Codex family but prefer project-based handoff and worktree review over a terminal-first loop.