Install and Update Codex CLI Before Your First Real Task

The wrong way to meet Codex CLI is to open a real repository first and hope setup sorts itself out along the way.

That usually creates a noisy first impression. A login problem looks like a product problem. A bad install path looks like a repo problem. Running on the wrong Windows surface looks like a model problem.

It is cleaner to separate those questions.

Use this page to get Codex CLI installed, authenticated, and updated without mixing channels. Then move into one real repo task only after the terminal surface is stable.

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 Official Channel#

The official Codex CLI page currently shows three sane install paths:

• global npm install
• Homebrew cask install
• latest GitHub release binary

For most developers, npm is the easiest starting point because the official page also publishes the matching npm upgrade command.

macOS Or Linux: Start With npm Unless You Already Standardize On Another Channel#

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 lists platform-specific archives for macOS and Linux.

The practical rule is simple: install from one channel and stick to that channel later when you update. Most weird PATH problems come from 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 causes the most avoidable confusion.

The official CLI page says Windows support for the CLI is experimental. The current Windows guide says the best Windows CLI experience is in WSL2, especially when your workflow already uses Linux-native tooling.

If your real work already lives in WSL2, or if you want the closest match to the Linux Codex workflow, do not start with a native Windows install out of habit. Start inside WSL2 instead.

The official Windows setup flow is:

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 guide also makes one operational point that matters later: 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 your team must run Codex natively on Windows, use the official Windows guide directly and treat native sandbox setup as its own task. Do not assume the native path and the WSL2 path behave the same.

What First Run Should Look Like#

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

A healthy first run looks like this:

• the shell recognizes codex
• Codex opens instead of failing with a missing-command error
• the login flow completes with the sign-in method you actually intended to use
• restarting codex does not immediately throw you back into auth confusion

One simple check works better than jumping straight into production code: create a scratch folder, launch codex there, 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 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 Reality Check Before You Blame Codex For A Bad First Task#

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

The agent approvals and security docs say the default workspace-write sandbox keeps network access off unless you enable it in configuration. They also show that approval policy and sandbox mode change what Codex can actually read, edit, or execute.

This matters because many first-task complaints are not really about code quality. They are about environment expectations:

• 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, learn the approval and sandbox defaults first.

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 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.