Codex CLI setup and first-use guide

Checked against the official docs on 2026-10-20. This guide is compiled from OpenAI's Codex documentation; FollowAgents has not yet run an install test on a current Codex release. Codex changes quickly, so the linked official pages win wherever they differ.

The two things that trip up a first Codex CLI run are rarely the install command. They are whether your ChatGPT plan includes the CLI at all, and what Codex is allowed to do the first time it runs. This guide takes them in that order, then covers Windows and common questions.

Still comparing tools? See Codex CLI's features, fit and source review, or Claude Code vs Codex.

First: which Codex does your plan include?

Sources: official pricing and feature availability and authentication. So the accurate answer to "is Codex free?": the Free plan currently offers Codex in the desktop app only; using the CLI in your terminal needs Plus or higher, or an API key billed per use. Prices and limits change — check the official page.

Step 1: Install the Codex CLI

On macOS or Linux, use the official installer (the same command updates it):

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On Windows, run this from a new PowerShell window:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm and Homebrew work too:

npm install -g @openai/codex
brew install --cask codex

Confirm with codex --version. Commands are from the official CLI page. The npm package is @openai/codex — don't install look-alike third-party packages.

Step 2: Sign in

Run codex in a project directory and it prompts you to sign in, or run:

codex login

The default is a browser flow — choose Sign in with ChatGPT. For an API key, the docs pipe it through stdin so it never lands in your shell history:

printenv OPENAI_API_KEY | codex login --with-api-key

On a remote machine without a browser, use device code sign-in (beta; enable device code login in your ChatGPT security settings first):

codex login --device-auth

Check the active method with codex login status. Credentials are cached in ~/.codex/auth.json (plain text) or your OS credential store — never commit that file. See the official authentication docs.

If --with-api-key is rejected as an unknown argument, your Codex is probably old: on version 0.33.0 we saw the earlier --api-key flag instead. Update with Step 1, then sign in.

Step 3: Your first task and its permissions

In a Git-tracked project, run codex and start with a question that changes nothing:

Tell me about this project

The docs recommend a Git commit before and after each task so you can roll back.

Two settings decide what Codex may do: the sandbox (where it can read and write, and whether it can reach the network) and approvals (when it asks you first). The official defaults:

• Version-controlled folders: the Auto preset, i.e. --sandbox workspace-write --ask-for-approval on-request. Codex reads, edits and runs commands inside the working directory, and asks before editing outside it or using the network.
• Folders not under version control: read-only.
• workspace-write keeps command network access off by default, and .git, .codex and .agents stay read-only even inside writable roots.

To chat or plan without changes, switch to read-only with /permissions, or start with:

codex --sandbox read-only --ask-for-approval on-request

--sandbox danger-full-access removes the sandbox; the docs ask for caution, and it is not a first-run setting. See official approvals and security.

Step 4: Make your habits stick with AGENTS.md and config.toml

• AGENTS.md: Codex reads it before doing any work. Global rules go in ~/.codex/AGENTS.md, project rules in the repository; files closer to the current directory take precedence, up to 32 KiB combined by default. Use it for agreements like "run npm test after editing JavaScript" or "ask before adding production dependencies". See official AGENTS.md docs.
• config.toml: personal defaults live in ~/.codex/config.toml, project overrides in the repo's .codex/config.toml — default model, approval and sandbox level. See official config basics.
• Usage: run /status in a session for remaining limits, or open the usage dashboard.

On Windows

Codex runs natively in PowerShell with the Windows sandbox — WSL is not required. For projects inside WSL2, Codex uses the Linux sandbox; in VS Code, set "chatgpt.runCodexInWindowsSubsystemForLinux": true to keep the agent inside WSL2. See the official Windows sandbox docs and the OS sandbox section of approvals and security.

Run the installer from a new PowerShell window, then open a fresh terminal before checking codex --version.

FAQ

Is Codex free? The ChatGPT Free plan currently includes Codex in the desktop app only, subject to rollout. The CLI and IDE extension need Plus or higher, or an API key billed at API rates. See the official pricing page.

API key or ChatGPT sign-in? An API key bills through your OpenAI Platform account at standard rates instead of plan usage, and features that rely on a ChatGPT workspace or cloud services (such as Codex cloud) are limited or unavailable. The docs recommend API keys for scripted workflows like CI/CD.

Is the Codex CLI open source? Yes — the source is at openai/codex under Apache-2.0. Codex Web is a separate hosted service.

Claude Code or Codex? Mostly a question of which plan you already have and which models you want. Plans, open source and model support are compared in Claude Code vs Codex.