Lesson 2: Install Codex and Sign In

Why setup matters more than it looks

In Level 1 you met the different forms of Codex. Now you'll put two of them on your machine: the CLI, which runs in your terminal, and the IDE extension, which runs inside your editor. Think of this level as setting up a new team member's laptop. You want the right version, the right account and a quick test in a real repository before you trust them with anything.

The one decision here that you'll live with is how you sign in. That choice decides who pays for the work and where your credentials are kept, so we'll take it slowly.

Step 1: Install the CLI

OpenAI now offers a standalone installer as well as the usual package managers. Pick one method:

# macOS / Linux: the official install script
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Or with a package manager you already use
npm install -g @openai/codex      # needs Node.js
brew install --cask codex         # macOS, Homebrew

# Windows (PowerShell): native installer
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Codex now runs natively on Windows in PowerShell, using its own Windows sandbox. You only need WSL2 if your tools and repositories already live in Linux. In that case, install Codex inside WSL and keep the repository on the Linux filesystem (~/code/...), not under /mnt/c/, where file access is slow.

Gotcha: two installs. If you install with npm and with brew or the script, your shell runs whichever copy comes first on your PATH. Then you upgrade one copy and wonder why nothing changed. Run which codex (or Get-Command codex in PowerShell) to see which copy you're running.

Step 2: Check the version against the release notes

Codex ships new versions often, often weekly, so "I installed it" is not the same as "I'm current".

codex --version
# example output: codex-cli 0.163.0

Now open the project's releases page at github.com/openai/codex/releases/latest. Release tags look like rust-v0.163.0. Compare the number after the v with your output. If yours is older, upgrade the same way you installed: run the script again, or use npm install -g @openai/codex@latest or brew upgrade --cask codex.

Why bother? Commands and flags change from release to release. When a tutorial, or this course, shows a flag your copy doesn't recognise, an out-of-date version is the first thing to check.

Step 3: Install the IDE extension

In VS Code, open the Extensions sidebar and search for ChatGPT, published by OpenAI (its ID is openai.chatgpt). The same extension works in VS Code-compatible editors such as Cursor and Windsurf. JetBrains IDEs and Xcode have their own integrations instead.

Once it's installed, click the Codex icon in the activity bar. If you can't see it, open the Command Palette (Ctrl+Shift+P) and run Codex: Open Codex Sidebar.

Tip: Check the publisher before you install. The marketplace has plenty of look-alike "Codex" and "GPT" extensions from other publishers.

Step 4: Sign in, and understand what you're choosing

You have two options:

codex login                     # opens a browser to sign in with ChatGPT
codex login --device-auth       # no browser on this machine (SSH, remote box): use a device code

# API key: pipe it in on stdin so it doesn't end up in your shell history
printenv OPENAI_API_KEY | codex login --with-api-key
# PowerShell equivalent:
# $env:OPENAI_API_KEY | codex login --with-api-key

codex login status              # which method is active right now?
codex logout                    # clear the cached credentials

In the IDE extension, the signed-out screen offers the same choice. Pick Use API Key if you want key-based billing.

Where the credentials are stored. Codex caches your login so you don't have to sign in every session. Depending on a setting called cli_auth_credentials_store, it uses a file (~/.codex/auth.json), your operating system's keyring, or auto, which tries the keyring first and falls back to the file. We'll cover the configuration file properly in Level 5. For now, the rule is: if auth.json exists, treat it like a password. Never commit it, never copy it into a container image and never paste it into a chat.

The CLI and the extension share the same cached login. If you sign out of one, you're signed out of both. That's handy, and it also explains why the extension sometimes suddenly asks you to sign in again.

Pitfall: If you sign in with ChatGPT and also have OPENAI_API_KEY exported for other tools, run codex login status to confirm which method Codex is actually using before you assume where the bill goes.

Step 5: First session in the practice repository

cd ~/code/practice-repo     # always start Codex from the repository root
codex                       # opens the interactive session

If Codex asks a first-run question about the folder, read it before you answer. Approvals and sandboxing come later in the course. For your first prompt, ask for something read-only, so nothing can go wrong:

Without changing any files, list the top-level folders in this repository,
say which language and test framework it uses, and name the file you
would read first to understand it.

You should get an answer that names real files from your repository, such as package.json and src/, and the test runner it found. Check them against ls yourself. Made-up file names, or "I can't see any files", usually mean you started Codex in the wrong directory.

Then ask the same question in the IDE sidebar with the repository open. The two answers should broadly agree.

Your task and how to check it

1. codex --version matches the latest tag on the releases page (or is at most one release behind).
2. codex login status reports the method you meant to choose.
3. The read-only prompt names at least three files or folders that really exist in the practice repository, in both the CLI and the extension.
4. git status shows no changes, which proves the session was read-only.

Key takeaways

• Install with one method (script, npm or brew, or the PowerShell installer on Windows) and check which copy is on your PATH.
• Compare codex --version with the GitHub releases page. Codex changes fast, and old versions miss newer flags.
• The IDE extension is OpenAI's ChatGPT extension in the marketplace (ID openai.chatgpt). It shares its login with the CLI.
• Signing in with ChatGPT uses your plan's included usage. An API key is billed per token through the Platform and has fewer workspace and cloud features.
• Cached credentials go to the OS keyring or ~/.codex/auth.json. Guard that file like a password.
• Start Codex from the repository root and make your first prompt read-only.