Installing and Authenticating Claude Code

Overview

This capsule takes you from zero to your first interaction with Claude Code. You're going to install it with the native installer Anthropic recommends, authenticate, verify everything works with the /doctor command, and fix the most common problems that can show up along the way.

There are no shortcuts here. A clean installation and solid authentication are the foundation of everything that follows. If something breaks at this step, every future session drags that problem along. If it all goes well — and this capsule makes sure it does — Claude Code simply works every time you need it.

By the end of this capsule you'll have Claude Code installed, authenticated, verified, and you'll have completed your first real interaction with the agent.

System requirements

Hard minimums

Node.js: The native installer handles dependencies automatically. You only need Node.js 18+ if you're going to use the programmatic SDK (Module 07).

Pre-check (macOS/Linux)

# Check that you can run curl
curl --version

You don't need to install anything else before proceeding.

Installing Claude Code

Claude Code offers 3 installation methods. The recommended one is the native installer, which updates itself automatically.

Method 1: Native installer (recommended)

macOS and Linux:

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

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows requires Git for Windows. Install it first if you don't have it.

Native installations update themselves automatically in the background.

Method 2: Homebrew (macOS)

brew install --cask claude-code

Note: Homebrew doesn't auto-update. Run brew upgrade claude-code periodically.

Method 3: WinGet (Windows)

winget install Anthropic.ClaudeCode

Note: WinGet doesn't auto-update. Run winget upgrade Anthropic.ClaudeCode periodically.

The native installer:

• Downloads and installs Claude Code, making it available as the claude command from any directory
• Sets up automatic background updates
• Typically takes 10-30 seconds depending on your connection

Step 2: Verify the installation

claude --version

Expected result:

claude-code v2.x.x

If you see a version number, the installation succeeded.

Step 3: First launch

claude

The first time you run claude, here's what happens:

1. The welcome banner appears
2. You're asked to accept the terms of use
3. The authentication flow starts
4. Once authenticated, you enter interactive mode

╭──────────────────────────────────────────╮
│ Claude Code                              │
│                                          │
│ /help for available commands             │
│ /doctor to check your setup              │
╰──────────────────────────────────────────╯

Authentication

Option 1: OAuth (recommended for interactive use)

OAuth is the simplest method. When you run claude for the first time:

1. Claude Code opens your browser automatically
2. It takes you to Anthropic's login page
3. You sign in with your account (email + password, or Google/GitHub)
4. You authorize Claude Code
5. The browser confirms the authorization
6. Claude Code in your terminal detects the authentication automatically

$ claude
Opening browser for authentication...
✓ Authenticated successfully

When to use OAuth:

• Daily use on your personal machine
• When you have a Pro or Max plan
• It's the "normal" flow for most users

Option 2: API Key (for programmatic use)

If you need to use Claude Code non-interactively (CI/CD, scripts, SDK), the API key is the way:

1. Go to console.anthropic.com/settings/keys
2. Create a new API key
3. Set the environment variable:

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"

To make it persist across terminal sessions:

echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

Or in bash:

echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

When to use an API Key:

• Use in CI/CD (GitHub Actions, GitLab CI)
• Automation scripts
• Headless SDK
• When there's no browser available (remote servers)

Comparison: OAuth vs API Key

The billing difference

This part matters, and it's a common source of confusion:

• OAuth connects to your subscription (Pro, Max 5x, Max 20x). You pay monthly and get an included usage limit.
• API Key connects to your API credit. You pay per token consumed. There's no fixed monthly cap — you pay for what you use.

You can have both configured. Plenty of professionals use OAuth for daily work and an API key for automations.

The /doctor command

What it is

/doctor is Claude Code's diagnostic command. It checks that your whole setup is correct and reports problems if it finds any.

How to run it

There are two ways:

From outside Claude Code:

claude doctor

From inside an interactive session:

> /doctor

What it checks

claude doctor inspects your installation and configuration, including:

✓ Authentication           → Are you authenticated?
✓ Network connectivity     → Can it reach Anthropic's servers?
✓ Model access             → Do you have access to the available models?
✓ Claude Code version      → Are you on the latest version?
✓ Permissions              → Can it read/write in the current directory?

Expected output (all good)

Claude Code Doctor
──────────────────

✓ Authenticated as user@email.com
✓ Network connection OK
✓ Model access: Opus 5, Sonnet 5
✓ Claude Code v2.x.x (latest)
✓ Directory permissions OK

All checks passed!

Output with problems

Claude Code Doctor
──────────────────

✗ Authentication: No valid credentials found
  → Run 'claude' to authenticate via OAuth
  → Or set ANTHROPIC_API_KEY environment variable
✓ Network connection OK
✗ Model access: Unable to verify (auth required)

2 issues found. Fix authentication to continue.

When to use /doctor

• After installing — confirm everything landed correctly
• When something fails — your first line of diagnosis
• After updating — check that the update didn't break anything
• On a new machine — fast setup + verification
• When models change — confirm access to the models you need

Updating and maintenance

Updating Claude Code

If you used the native installer, Claude Code updates itself automatically in the background. You don't have to do anything.

To force a manual update:

claude update

Check the version:

claude --version

If you used Homebrew or WinGet (they don't auto-update):

# Homebrew
brew upgrade claude-code

# WinGet
winget upgrade Anthropic.ClaudeCode

When to check for updates

• Native installation: Updates arrive automatically
• Homebrew/WinGet: Check weekly, or whenever you need a new feature
• Immediately: When Claude Code shows a new-version message

Troubleshooting

Problem 1: "command not found" after installing

Symptom: zsh: command not found: claude

Most common cause: The binary isn't on your PATH.

# With the native installation, try closing and reopening your terminal
# The installer adds claude to the PATH automatically

# If it persists, check where it got installed
which claude

# On macOS/Linux, it may be in /usr/local/bin/ or ~/.local/bin/

If you used Homebrew, check that brew is on your PATH and reinstall.

Problem 2: Permission errors

Symptom: The installer fails on permissions.

Fix:

# macOS/Linux: the native installer normally doesn't require sudo
# If it fails, check that your user has write permissions on /usr/local/bin/

# If you use Homebrew, it handles permissions automatically
brew install --cask claude-code

Problem 3: Expired authentication token

Symptom: Authentication error: Token expired or invalid

claude logout
claude
# Forces a fresh login flow

For an API key: check it with echo $ANTHROPIC_API_KEY and set it again if it's empty.

Problem 4: Network / proxy errors

Symptom: Network error: Unable to connect to Anthropic API

If you're behind a corporate proxy:

export HTTPS_PROXY="http://proxy.company.com:8080"

Claude Code needs access to api.anthropic.com and console.anthropic.com.

Problem 5: Claude Code installs but won't launch

Clean reinstall:

# macOS/Linux — reinstall with the native installer
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew
brew reinstall --cask claude-code

Complete walkthrough: from zero to your first interaction

# 1. Install Claude Code (native installer)
curl -fsSL https://claude.ai/install.sh | bash

# 2. Verify the installation
claude --version  # claude-code v2.x.x

# 3. Run it for the first time
claude
# → Accept the terms of use
# → The browser opens for authentication
# → Sign in to Anthropic → Authorize → Back to the terminal

# 5. Verify the setup
> /doctor
# Every check should pass

# 6. First real interaction
> What files are in this directory?

# 7. Try a task
> Create a hello.py file that prints "Claude Code works"

# 8. Exit
> /exit

If every step produced the expected result, your installation is complete.

Comparisons and decisions

OAuth or API Key?

How are you going to use Claude Code?

├─ Daily, interactive, on your machine
│  → OAuth (simpler, renews itself)
│
├─ CI/CD, scripts, automation
│  → API Key (no browser required)
│
├─ Both: daily use + automations
│  → OAuth for interactive + API Key for scripts
│
└─ Remote server with no GUI
   → API Key (no browser available)

Native installation or Homebrew/WinGet?

Do you want automatic updates?

├─ Yes (recommended)
│  → Native installer (auto-updates in the background)
│
└─ No, I'd rather control updates
   → Homebrew or WinGet (you update manually)

Common patterns

Pattern 1: Setup on a new machine

When you set up a new machine or start at a new company:

curl -fsSL https://claude.ai/install.sh | bash
claude
# Authenticate
claude doctor
# Verify everything

2 minutes, complete setup. No prior Node.js dependencies.

Pattern 2: Check the version periodically

With a native installation, updates are automatic. Confirm you're current:

claude --version

If you used Homebrew: brew upgrade claude-code periodically.

Pattern 3: Quick check before an important session

Before a critical development session:

claude doctor

If everything's green, go. If something fails, better to fix it before you start.

Pattern 4: Re-authentication after a vacation

After days without using Claude Code, your token may have expired:

claude
# If it asks you to re-authenticate, follow the flow
# If it goes straight in, you're fine

Pitfalls and edge cases

Pitfall 1: Installing the wrong way

The recommended native installer (curl -fsSL https://claude.ai/install.sh | bash) handles everything automatically. Avoid unofficial installation methods, and avoid installing with sudo when it isn't necessary.

Pitfall 2: Not verifying with /doctor

"It installed, it works, done." Until it doesn't. /doctor catches latent problems that aren't obvious in a simple interaction but surface in real use.

Pitfall 3: An API key hardcoded in a committed script

ANTHROPIC_API_KEY="sk-ant-xxxxx" claude "do something"

If this script gets committed, your API key is exposed. Use environment variables from a .env (that's in .gitignore) or a secret manager.

Pitfall 4: An old version of Claude Code

Claude Code updates frequently. A version from two weeks ago may not have features the docs describe. If something "should work but doesn't", update first.

Pitfall 5: Confusing the native installation with npm (deprecated)

If you used to run npm install -g @anthropic-ai/claude-code, migrate to the native installer: curl -fsSL https://claude.ai/install.sh | bash and then npm uninstall -g @anthropic-ai/claude-code. The npm method is deprecated.

Pitfall 6: WSL2 on Windows — mixed paths

In WSL2, mixing Windows paths (C:\Users\...) with Linux paths (/home/...) causes problems. Always work inside the WSL2 filesystem (/home/your-user/) to avoid conflicts.

Complete worked example

Scenario: Professional setup from scratch on macOS

# 1. Install Claude Code (no Node.js needed)
curl -fsSL https://claude.ai/install.sh | bash

# 2. Verify
claude --version  # claude-code v2.x.x

# 3. First launch + authentication
claude
# → Browser flow → Login → Authorize → Back to the terminal

# 4. Verify the full setup
> /doctor
# Every check should pass

# 5. First real task
> What directory am I in and what files are here?
> /exit

Scenario: Setup for CI/CD

# .github/workflows/ci.yml
- name: Claude Code Review
  run: |
    curl -fsSL https://claude.ai/install.sh | bash
    claude -p "Review this PR and give feedback" --output-format json
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Scenario: Re-setup after problems

# Clean reinstall
curl -fsSL https://claude.ai/install.sh | bash
claude logout
claude         # New authentication flow
> /doctor      # Verify

Practice exercises

Exercise 1: Complete installation

Install Claude Code following the steps in this capsule. Verify each step.

Checklist:

• Native installer run (curl -fsSL https://claude.ai/install.sh | bash)
• claude --version shows a version
• claude launches and you authenticate
• /doctor passes every check

Exercise 2: Diagnosis with /doctor

Run /doctor and analyze every line of the output.

1. Are you authenticated? With OAuth or an API key?
2. Which models do you have access to?
3. Are you on the latest version of Claude Code?

Exercise 3: First real task

With Claude Code open in a project directory (or any directory), run:

> Explain the file structure of this directory

Evaluate the answer: could Claude Code read the files? Is the description accurate?

Exercise 4: Simulate and solve a problem

Trigger an error on purpose and fix it:

1. Close your session: /exit
2. Temporarily invalidate your authentication (rename the credentials file or change the API key)
3. Try opening Claude Code
4. Observe the error
5. Restore authentication and verify with /doctor

claude logout
claude
# Go through the authentication flow again

# Save your current key
OLD_KEY=$ANTHROPIC_API_KEY

# Invalidate the key
export ANTHROPIC_API_KEY="invalid-key"

# Try using Claude Code
claude
# You'll see an authentication error

# Restore
export ANTHROPIC_API_KEY=$OLD_KEY

# Verify
claude doctor

Exercise 5: Update and verify

Check whether there's a newer version of Claude Code and update if needed.

claude --version
claude update
claude --version
claude doctor

Summary

• Installation: curl -fsSL https://claude.ai/install.sh | bash (native, recommended) or via Homebrew/WinGet
• Authentication: OAuth for interactive use (browser flow), API key for programmatic use (environment variable)
• Verification: /doctor is your diagnostic tool — use it after installing, after updating, or whenever something breaks
• Updating: Automatic with the native installation, claude update to force it
• Troubleshooting: The most common problems are PATH not configured, permissions, and expired tokens
• Always the first step: native installer → claude → /doctor
• OAuth vs API key: They're not mutually exclusive — you can use both for different purposes
• WSL2 on Windows: Work inside the WSL2 filesystem, not in Windows paths

Next capsule: 03 - Available platforms — Claude Code doesn't only live in the terminal. Find out where else you can use it and when to pick each platform.

Additional resources

1. Advanced Setup — System requirements, per-platform installation, updates, and uninstallation
2. Authentication — Every authentication method (OAuth, API key, third-party providers)
3. Claude Code CLI Reference — Complete reference of commands, flags, and options
4. Troubleshooting — Solutions to common installation and usage problems
5. Anthropic Console — API Keys — Create and manage API keys
6. Git for Windows — Required for the native installation on Windows
7. WSL2 Installation Guide — Set up Windows Subsystem for Linux 2 (optional on Windows)
8. Claude Code GitHub Discussions — Community and support for installation problems