Originally published at heycc.cn. This is a mirrored copy — the canonical version is kept up to date at the source.

Claude Code Setup in 2026: Install Paths, Auth, and the First-Run Errors People Actually Hit

Claude Code in 2026 is no longer "an npm package you install and log into." It is one agent shipped across three surfaces — a native CLI binary, a VS Code extension that bundles its own private copy of that binary, and a full desktop app — and the setup failures people search for are almost all seam problems between those surfaces: the extension that doesn't put claude on your PATH, the environment variable that silently outranks the subscription you're paying for, the install script that returns a 403 and dumps HTML into your shell, the npm install that succeeds but can't find its native binary.

What follows maps that whole surface area as it exists in July 2026, verified against the official docs and pricing pages on 2026-07-18 — including real terminal output captured on a Windows 11 machine that turned out to be a textbook case of the seam problem described above. If you only take away four things, take these, because they are the ones the official docs state but never connect:

1. An approved ANTHROPIC_API_KEY in your environment silently outranks your paid subscription — you can pay for Pro and still be billed metered API credits.
2. "claude: command not found" after installing the VS Code extension or desktop app is by design — both bundle a private CLI and add nothing to PATH.
3. A 403 during install and a 403 after login are different diseases — one is distribution/region/proxy, the other is subscription-or-role, and the docs treat them in different sections.
4. Homebrew's claude-code cask runs a week behind on purpose — the stable/latest channel split explains most "my teammate has a feature I don't" confusion.

The 2026 install landscape: one binary, many wrappers

The most important architectural fact to understand before typing anything: every install path now delivers the same native binary. This was not always true. Claude Code launched as a Node.js CLI distributed via npm; through 2025 it migrated to a self-contained native executable. As of v2.1.198, even the npm package (@anthropic-ai/claude-code) is just a delivery wrapper — it pulls in a per-platform optional dependency such as @anthropic-ai/claude-code-darwin-arm64 and a postinstall step links the native binary into place. The setup docs are explicit that the installed claude binary does not invoke Node at runtime.

That means the decision between install methods is no longer about runtimes. It is about exactly two things: who manages updates, and what your environment allows.

Install path	Command	Auto-updates?	Best for
Native installer (official recommendation)	`curl -fsSL https://claude.ai/install.sh \	bash` (macOS/Linux/WSL)	Yes, in background
Native installer, Windows PowerShell	`irm https://claude.ai/install.ps1 \	iex`	Yes
Native installer, Windows CMD	curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd	Yes	CMD-only environments
Homebrew	brew install --cask claude-code	No (manual brew upgrade)	Mac fleets standardized on brew
WinGet	winget install Anthropic.ClaudeCode	No (manual winget upgrade)	Windows fleets standardized on winget
apt / dnf / apk	Signed repos at downloads.claude.ai	No (system upgrade workflow)	Linux servers, containers, compliance environments
npm	npm install -g @anthropic-ai/claude-code	Only if npm global dir is writable	Teams whose tooling already assumes npm

Three rows hide real failure modes.

Homebrew ships two casks with different release channels. claude-code tracks the stable channel — typically about a week behind, skipping releases with major regressions — while claude-code@latest tracks every release as it ships. If a teammate on the native installer has a feature your brew install lacks, this channel split is usually why. Native installs pick the same channels via the autoUpdatesChannel setting ("latest" is the default). One extra brew-specific trap from the troubleshooting docs: Cask 'claude-code' is unavailable almost always means a stale local cask index — brew update first, then install.

The Linux package repos are GPG-signed, and the docs publish the fingerprint. Before trusting the key at https://downloads.claude.ai/keys/claude-code.asc, verify it reports 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE (listed on the setup page). Each repo offers stable and latest channel URLs. For air-gapped or compliance-heavy environments, every release additionally publishes a manifest.json with SHA256 checksums for all platform binaries, signed with the same key — verifying the manifest signature transitively verifies every binary it lists.

Only the native installer auto-updates by default. Homebrew and WinGet installs can opt in by setting CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1, which makes Claude Code run the upgrade command in the background; apt/dnf/apk always require manual upgrades because those need elevated privileges. The release cadence makes staleness a real cost: the docs' own example version strings span 2.1.89 to 2.1.211 across pages, the machine used for this article's captures was on 2.1.209, and behavior notes in the docs are routinely gated on micro-versions ("requires v2.1.203 or later", "before v2.1.208...").

System requirements

Verified from the setup page: macOS 13.0+, Windows 10 1809+ or Windows Server 2019+, Ubuntu 20.04+/Debian 10+/Alpine 3.19+; 4 GB+ RAM on x64 or ARM64; an internet connection; a supported country. Shell support covers Bash, Zsh, PowerShell, and CMD. Alpine users need an extra step — apk add bash curl libgcc libstdc++ ripgrep plus USE_BUILTIN_RIPGREP=0 in settings — because the musl builds don't bundle everything the glibc builds do.

Installing on each platform

macOS, Linux, WSL

curl -fsSL https://claude.ai/install.sh | bash

The installer places a launcher at ~/.local/bin/claude as a symlink into ~/.local/share/claude/versions/. That layout matters for two later scenarios: uninstalling (remove both paths), and custom launchers (since v2.1.207, if you replace the symlink with your own script, auto-update leaves it alone and installs new versions alongside — but then keeps every version on disk because it can't tell which one your launcher needs; both behaviors are documented under auto-updates on the setup page).

You can pin at install time: bash -s stable installs the stable channel, bash -s 2.1.89 installs an exact version, and the channel you choose at install time becomes your auto-update default.

Windows: the PowerShell/CMD confusion, solved

Windows has two different install commands for two different shells, and running the wrong one in the wrong shell is common enough that the official docs include error-message-based shell detection:

• Seeing The token '&&' is not a valid statement separator? You're in PowerShell but ran the CMD command. Use irm https://claude.ai/install.ps1 | iex.
• Seeing 'irm' is not recognized as an internal or external command? You're in CMD but ran the PowerShell command. Use the curl ... install.cmd sequence.
• Seeing A parameter cannot be found that matches parameter name 'fsSL'? You ran the macOS/Linux command in PowerShell, where curl is an alias for Invoke-WebRequest.
• Your prompt tells you which shell you're in: PS C:\Users\You> is PowerShell; the same prompt without PS is CMD.

No administrator rights are needed for either.

The bigger Windows decision is native vs WSL, and the official guidance is a clean three-row trade-off:

Option	Requires	Sandboxing	When to use
Native Windows	Nothing (Git for Windows optional)	Not supported	Windows-native projects and tools
WSL 2	WSL 2 enabled	Supported	Linux toolchains, sandboxed command execution
WSL 1	WSL 1 enabled	Not supported	Only if WSL 2 is unavailable

On native Windows, Git for Windows is optional but consequential: with it, Claude Code gets a real Bash tool via Git Bash; without it, shell commands run through a PowerShell tool instead. If Git Bash is installed but not found, point to it explicitly in settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

If you choose WSL, install inside the WSL terminal using the Linux command — not from PowerShell.

The npm route: still alive, but read the fine print

npm install -g @anthropic-ai/claude-code

Four gotchas, all documented and all commonly hit:

1. Node.js 22+ is required as of v2.1.198 — but on older Node, npm prints an EBADENGINE warning rather than failing, and the install still completes and works, because the binary doesn't use your Node at runtime. This asymmetry confuses people who see the warning and assume breakage.
2. Never sudo npm install -g. The docs warn this causes permission issues and security risks. If you hit EACCES, fix the npm prefix instead.
3. Upgrade with npm install -g @anthropic-ai/claude-code@latest, not npm update -g — npm update respects the semver range from your original install and may silently leave you on an old release.
4. Optional dependencies must be enabled. The native binary arrives via a per-platform optional dependency, so --omit=optional, pnpm's --no-optional, yarn's --ignore-optional, or optional=false in a .npmrc produce a broken install that fails with Could not find native binary package — there is no JavaScript fallback. Prebuilt binaries exist for exactly eight platforms: darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, win32-arm64. Anything else (FreeBSD, 32-bit, exotic ARM) has no binary to find — and before v2.1.205 the installer even misdetected FreeBSD as Linux and downloaded a binary that couldn't run.

A subtle related case: installing with --ignore-scripts does not break the install — the postinstall linking step is skipped, so Claude Code falls back to a wrapper that locates and spawns the platform binary on each launch. Slower startup, but functional.

Verify the install — with real output

Two commands, both worth running before your first session. What follows is genuine output captured for this article on 2026-07-18, on a Windows 11 x64 machine (usernames redacted) — a machine that happens to demonstrate the exact seam problem this guide keeps warning about, because Claude Code on it runs only through the desktop app.

First, the failure you'll see if you expect the desktop app (or the VS Code extension) to have put claude on your PATH. Real PowerShell output:

claude : The term 'claude' is not recognized as the name of a cmdlet, function,
script file, or operable program. Check the spelling of the name, or if a path
was included, verify that the path is correct and try again.

This is not a broken install. The desktop app bundles its own private copy of the CLI (on this machine, under %APPDATA%\Claude\claude-code\2.1.209\claude.exe) and the quickstart docs say plainly that to use claude from a terminal you install the CLI separately. Invoking that bundled binary directly by full path works fine:

PS> & "$env:APPDATA\Claude\claude-code\2.1.209\claude.exe" --version
2.1.209 (Claude Code)

(The setup docs' own example output is 2.1.211 (Claude Code) — two releases ahead of this machine, a nice live demonstration of the release cadence.)

Now the diagnostic command, run against that same bundled binary. Real, unedited output apart from username redaction:

PS> & "$env:APPDATA\Claude\claude-code\2.1.209\claude.exe" doctor
Claude Code doctor

Running: native (2.1.209)
Commit: 0fe048596fd4
Platform: win32-x64
Path: C:\Users\<user>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude-code\2.1.209\claude.exe
Config install method: unknown
Search: OK (bundled)
Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER)
Auto-update channel: latest
Last update attempt: none recorded

Remote Control
Remote Control requires a claude.ai subscription. Run claude auth login to sign in with your claude.ai account.
- Not signed in to claude.ai
- claude.ai subscription auth not active
- Sign-in is missing the user:profile scope

4 warnings found
- Native installation exists but C:\Users\<user>\.local\bin is not in your PATH
  Fix: Add it by opening: System Properties → Environment Variables → Edit User PATH → New → Add the path above. Then restart your terminal.
- Running native installation but config install method is 'unknown'
  Fix: Run claude install to update configuration
- claude command at C:\Users\<user>\.local\bin\claude.exe missing or broken (C:\Users\<user>\.local\bin does not exist)
  Fix: Run claude install to repair the installation.
- claude command at C:\Users\<user>\.local\bin\claude.exe missing or broken
  Fix: Run claude install to repair the installation.

For a full setup checkup that can also fix issues, run /doctor in a Claude Code session.

Three things worth reading out of that output, because they generalize:

• claude doctor is read-only and runs without starting a session. It reports the running version, commit, platform, resolved binary path, how the config thinks it was installed, auto-update status and channel, and the last update attempt — plus warnings with concrete fixes. Note the desktop app manages its own updates and sets DISABLE_AUTOUPDATER for its bundled CLI; if you see that line on a standalone install, something in your environment set it.
• Doctor checks the standard install location (~/.local/bin/claude, or %USERPROFILE%\.local\bin\claude.exe on Windows) and flags it when it's missing or broken — which is exactly what you see above, since only the app-bundled copy exists on this machine. For genuinely conflicting installations (an old npm global alongside a newer native install — the classic "I updated but the version didn't change"), the docs don't claim doctor resolves it; they give a manual procedure instead: which -a claude on macOS/Linux or where.exe claude on Windows, then check ~/.claude/local/ (legacy local npm install) and npm -g ls @anthropic-ai/claude-code, and remove everything except the native install.
• The fix lines are actionable but context-blind. On this machine, running claude install as doctor suggests would create a second, standalone installation alongside the desktop app's bundled one — reasonable if you want the CLI in your terminal, surprising if you don't. Doctor diagnoses; it doesn't know your intent.

Authentication: what's free, what's not, and the precedence trap

The free-tier question, answered bluntly

The setup docs state it verbatim: "The free Claude.ai plan does not include Claude Code access." Claude Code requires a Pro, Max, Team, Enterprise, or Console account — the software itself (CLI, extension, desktop app) installs free, but no session runs without one of those. The billing routes:

Route	Cost (verified 2026-07-18)	Billing model	Best for
Claude Pro	$17/mo billed annually ($200 up front), $20/mo monthly	Flat subscription, usage limits apply	Individuals; the recommended path
Claude Max	From $100/mo	Flat subscription, "5x or 20x more usage than Pro"	Heavy daily agent use
Claude Team	$20/seat/mo annual ($25 monthly) standard; $100/seat/mo annual ($125 monthly) premium	Per-seat subscription	Teams wanting central admin
Console account	Pre-paid API credits, pay per token	Metered	Occasional use, scripting, cost isolation

One Console-specific detail that becomes a support ticket if missed: Console users must be assigned a role before Claude Code works. Admins invite users under Settings → Members and grant either the Claude Code role (can only create Claude Code API keys) or the Developer role (can create any API key). A Console login without one of those roles produces a 403 after login — covered in the error decoder below.

For truly occasional use, prepaid Console credits can be cheaper than a subscription; for anything approaching daily use, the flat-rate subscription almost always wins, which is why the docs mark it "recommended."

The login flow

Run claude in a project directory. A browser window opens for OAuth; press c if it doesn't, which copies the URL to open manually. In WSL2, over SSH, or inside containers — anywhere the browser can't reach the CLI's local callback server — the browser shows a login code instead of redirecting, which you paste at the "Paste code here if prompted" prompt. If pasting into the interactive prompt does nothing (a real terminal-binding issue the docs now cover), claude auth login reads the pasted code from standard input instead. Afterward: /status shows which auth method is active, /login switches accounts, /logout signs out.

Credentials land in the encrypted macOS Keychain on Mac, ~/.claude/.credentials.json (mode 0600) on Linux, and %USERPROFILE%\.claude\.credentials.json on Windows. For CI, claude setup-token mints a one-year OAuth token (subscription plans only) that you export as CLAUDE_CODE_OAUTH_TOKEN — strictly better than baking an API key into CI when you're paying for a subscription anyway. Two documented limits: the token can only make model requests (no Remote Control sessions, no claude.ai connectors), and bare mode (--bare) doesn't read it at all.

The precedence trap: your API key silently outranks your subscription

This is the single most expensive misconfiguration in the whole setup, and it's invisible unless you know to look. When multiple credentials exist, Claude Code resolves them in this exact documented order:

1. Cloud-provider flags (CLAUDE_CODE_USE_BEDROCK / VERTEX / FOUNDRY)
2. ANTHROPIC_AUTH_TOKEN
3. ANTHROPIC_API_KEY
4. apiKeyHelper script
5. CLAUDE_CODE_OAUTH_TOKEN
6. Subscription OAuth from /login

Note that subscription login is last. If you approved an ANTHROPIC_API_KEY from your dotfiles months ago — say, from an old SDK experiment — every Claude Code session bills metered API credits while your Pro subscription sits unused. The docs list this order; what they don't spell out in one place is the billing consequence, so here it is: you can pay $200/year for Pro and never use a cent of it.

The guardrails, precisely: in interactive mode you're prompted once to approve or decline the key, and the choice is remembered — reversible later via the "Use custom API key" toggle in /config, which only appears while the variable is set. In non-interactive mode (claude -p), the key is always used when present, with no prompt at all — so a scripted invocation can be billing your Console account even though interactive sessions use your subscription.

The trap also has a louder failure mode the docs document separately: if the stale key belongs to an organization that's since been disabled, you get API Error: 400 ... "This organization has been disabled" despite an active subscription — pure precedence, not a billing problem. Either way the diagnosis is the same: run /status (the Login method row shows your subscription; an API key row appears when a key is in use), unset ANTHROPIC_API_KEY, remove the export from your shell profile (on Windows, check $PROFILE and your User environment variables), and /login.

The VS Code extension

The extension (Marketplace ID anthropic.claude-code, requires VS Code 1.98.0+) gives you a chat panel with three permission modes — Manual, Plan (which opens the plan as an editable Markdown document you can annotate with inline comments before execution), and Edit automatically. It works in Cursor via cursor:extension/anthropic.claude-code and in Open VSX-based forks. Auth-wise it needs any paid Claude subscription or Console account; the docs note explicitly that no API key is required.

Two facts about the extension prevent most of its support tickets:

It bundles its own private CLI and does not touch your PATH. The troubleshooting docs put it flatly: "If you have only installed the extension, ~/.local/bin/claude will not exist." So installing the extension and then typing claude in the integrated terminal fails with the exact not recognized error captured in the verification section above — not a bug, just a missing second install. The two installs coexist happily and share conversation history: claude --resume in a terminal picks up a conversation you started in the extension panel.

GUI-launched VS Code doesn't inherit your shell environment. If ANTHROPIC_API_KEY is exported in your .zshrc but the extension still shows a sign-in prompt, it's because VS Code launched from the dock/Start menu never sourced your shell profile. Launch it from a terminal with code . — or better, just sign in with your Claude account, which sidesteps the environment entirely (and avoids the precedence trap above). The same non-inheritance bites cloud-provider users: Bedrock/Vertex/Foundry variables set in your shell don't reach a GUI-launched IDE either.

Extension vs CLI: what you give up in the panel

Capability	CLI	VS Code extension
Slash commands and skills	All	Subset
! bash shortcut	Yes	No
Tab completion	Yes	No
Adding MCP servers	claude mcp add	Not directly — add via CLI, then manage with /mcp in the panel
Checkpoints / rewind	Yes	Yes
Plan mode as editable document	Terminal UI	Yes — Markdown doc with inline comments

The practical workflow that falls out of this table: install both, use the extension for review-heavy interactive work (its Plan-as-document mode is genuinely better than the terminal for annotating a plan), and drop to the CLI for MCP configuration, scripting, and anything automated.

The desktop app

The desktop app graduated from wrapper to full product surface, with three tabs: Chat (general conversation, no file access), Cowork (an autonomous background agent in a sandboxed VM, local or Anthropic-managed), and Code (the interactive coding surface with direct file access). Downloads cover macOS (universal build for Intel and Apple Silicon), Windows x64 and ARM64, and Linux in beta via apt/.deb for Ubuntu and Debian. On Windows, Git must be installed for local Code sessions to work.

The Code tab runs sessions in four environments — Local (your machine, your files), Remote (Anthropic cloud infrastructure that keeps running after you close the app), SSH (Claude Code auto-installs on the remote host the first time you connect), and WSL on Windows. Its headline scaling feature: parallel sessions opened from the sidebar each run in their own Git worktree, so simultaneous tasks on the same repo don't collide until you choose to commit. The CLI equivalent is the --worktree flag. The docs' positioning is symmetric and worth trusting: desktop runs the same engine as the CLI, shares configuration with it (CLAUDE.md, MCP servers, hooks, skills, settings), and both can run on the same project at once.

Two auth caveats for this surface. First, as the doctor output above showed, the app bundles its own CLI and puts nothing on PATH — terminal use requires a separate standalone install. Second, desktop sessions don't read ANTHROPIC_API_KEY and don't call apiKeyHelper; they authenticate via OAuth (with one documented exception: desktop sessions running a third-party inference / LLM-gateway configuration authenticate with that configuration's credential). If your setup is Console-key-based CI plus desktop for interactive work, the desktop side still needs a real account login — and if the Code tab shows a 403, the desktop docs' dedicated fix is to sign out and back in.

First-run error decoder

These are the errors people actually search, mapped to documented causes and fixes.

Error / symptom	What it means	Fix
curl: (22) The requested URL returned error: 403 during install	The install URL returned an error status instead of the script	If any returned HTML says "App unavailable in region," Claude Code isn't available in your country. Otherwise check connectivity first (curl -sI https://downloads.claude.ai/claude-code-releases/latest) — the docs note the alternative installers reach the same hosts, so a blocked network blocks them too. If connectivity is fine, retry (often transient) or try Homebrew/WinGet
syntax error near unexpected token '<'	Bash tried to execute HTML — same root cause as the 403 (script URL returned a page, not a script)	Same as above
PowerShell: Invoke-Expression: Missing argument in parameter list	The PowerShell flavor of the same problem — irm fetched an error page	Same as above
CRYPT_E_NO_REVOCATION_CHECK / CRYPT_E_REVOCATION_OFFLINE on Windows	curl reached the server but your network blocks certificate-revocation lookups; --ssl-revoke-best-effort doesn't help because it only covers downloading install.cmd, not the script's own downloads	Use the PowerShell installer (downloads via .NET, tolerates the blocked lookup) or winget install Anthropic.ClaudeCode, which avoids curl entirely
The token '&&' is not a valid statement separator	You ran the CMD install command in PowerShell	Use `irm https://claude.ai/install.ps1 \
{% raw %}'irm' is not recognized	You ran the PowerShell command in CMD	Use the curl ... install.cmd sequence
claude: command not found after installing the VS Code extension or desktop app	Both bundle a private CLI; nothing was added to PATH	Install the standalone CLI with the native installer
Could not find native binary package after npm install	Optional dependencies disabled, or unsupported platform	Remove --omit=optional / --no-optional / optional=false from your npm/pnpm/yarn config and reinstall; confirm you're on one of the 8 supported platforms
EBADENGINE warning during npm install	Node older than 22	Cosmetic — install completes and the binary runs without Node — but upgrade Node to silence it
Extension shows sign-in despite ANTHROPIC_API_KEY in shell	GUI-launched VS Code didn't inherit shell env	Launch with code . from a terminal, or sign in with your Claude account
Billed API credits despite active Pro subscription	An approved env API key outranks subscription OAuth (precedence rule 3 vs 6); in -p mode the key is used with no prompt	/status to confirm, unset ANTHROPIC_API_KEY, /login
API Error: 400 ... "This organization has been disabled" with an active subscription	Same precedence trap, louder: the overriding key belongs to a disabled org	Unset the key, remove it from your shell profile, /login
API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}} after login	Auth-side, not network-side: inactive subscription, missing Console role, or proxy interference	Pro/Max: verify the subscription is active at claude.ai/settings. Console: an admin must assign the "Claude Code" or "Developer" role under Settings → Members. Behind a corporate proxy: check proxy configuration
403 or authentication errors in the desktop app's Code tab	Desktop-side auth state is stale	Sign out of the app and back in (dedicated section in the desktop docs)
Sessions error only inside WSL2/SSH/containers at login	Browser redirect can't reach the CLI's callback server	Use the login-code flow; if pasting fails, claude auth login reads the code from stdin

On the specific search term "claude code vscode 403": the docs describe two unrelated 403s, and conflating them wastes hours. A 403 before you ever authenticate — during install or first download — is the distribution layer: region availability, a corporate proxy, or transient routing, and the region check (does any returned page say "App unavailable in region"?) tells you whether it's fixable on your end at all. A 403 after login succeeds — API Error: 403 ... Request not allowed in the extension, CLI, or desktop Code tab — is an account problem: your Pro/Max subscription lapsed, or your Console account was never granted the "Claude Code"/"Developer" role, or a corporate proxy is mangling API requests. The first disease is diagnosed with curl -sI against downloads.claude.ai; the second with a look at your subscription page or a question to your Console admin.

Recommended setups, by situation

• Individual on macOS/Linux: native installer + Claude Pro. Before your first session, run env | grep ANTHROPIC — if ANTHROPIC_API_KEY is set from some old experiment, unset it now or decline it at the approval prompt, or it will outrank the subscription you're about to pay for. Add the VS Code extension if that's your editor; keep the CLI for MCP setup and scripting. The two share history via claude --resume.
• Individual on Windows: native PowerShell installer (irm https://claude.ai/install.ps1 | iex). Choose native Windows unless you need sandboxed command execution — that requires WSL 2, installed from inside the WSL terminal. Install Git for Windows to get a real Bash tool; set CLAUDE_CODE_GIT_BASH_PATH if Claude can't find it.
• Desktop-app-first users: remember the app's CLI is private (the doctor output above is what that looks like). If you ever want claude in a terminal, run the standalone installer too — they coexist and share configuration.
• Mac/Windows fleets on brew/winget: accept the manual-upgrade model or set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1. On brew, decide deliberately between claude-code (stable, ~a week behind) and claude-code@latest, and put the choice in your onboarding docs — mixed channels across a team is how "works on my machine" divergence starts.
• CI pipelines: claude setup-token on a subscription plan, exported as CLAUDE_CODE_OAUTH_TOKEN. Know its limits: model requests only, and --bare ignores it (use an API key or apiKeyHelper there). If CI must use a Console key instead, remember -p mode uses ANTHROPIC_API_KEY unconditionally — cost attribution follows the key, not the runner's login.
• Servers, containers, compliance environments: the signed apt/dnf/apk repos, with the GPG fingerprint verified and manifest.json checksums for air-gapped mirroring. Behind a proxy, set HTTPS_PROXY before installing and NODE_EXTRA_CA_CERTS for TLS-inspecting middleboxes. Login uses the code-paste flow since there's no local browser.
• Console-billed teams: assign the "Claude Code" or "Developer" role at invite time — a role-less Console login is the most common cause of the post-login 403 — and prefer the Claude Code role for least privilege unless users need general API keys.

What was checked, and where

All install commands, system requirements, channel behavior, the GPG fingerprint, the eight npm platform packages, Node 22/EBADENGINE behavior, and version-gated claims (v2.1.116, v2.1.198, v2.1.203, v2.1.205, v2.1.207, v2.1.208, v2.1.211) were checked against the Claude Code setup and troubleshoot-install docs on 2026-07-18. The authentication precedence order, the -p//config API-key behavior, credential storage paths, setup-token limits, and the desktop OAuth exception were checked against the authentication docs the same day. Desktop-app claims (three tabs, four session environments, per-sidebar-session worktrees, Windows Git requirement, Linux beta) were checked against the desktop quickstart. Pricing figures were checked against claude.com/pricing. The claude --version and claude doctor transcripts were captured live on 2026-07-18 on a Windows 11 x64 machine running Claude Code 2.1.209 via the desktop app's bundled CLI; usernames are redacted, and no other edits were made to the output.

Sources

• Claude Code setup — install methods, requirements, release channels
• Troubleshoot installation and login — official error reference
• Authentication — precedence order, credential storage, setup-token
• Claude Code in VS Code — extension capabilities and limits
• Desktop app quickstart — tabs, environments, platform downloads
• Claude pricing — Pro, Max, and Team plans