Installation & Authentication

The installer is a single curl command that handles the entire setup. After that, authentication takes one of three paths: OAuth (opens a browser), API key (for headless or CI/CD), or SSO (for enterprise). This lesson covers all three paths and verifies everything works.

What you'll learn

• One command installs on macOS, Linux, or WSL: curl -fsSL https://claude.ai/install.sh | bash
• Windows users have two options: PowerShell (irm https://claude.ai/install.ps1 | iex) or winget install Anthropic.ClaudeCode
• Authentication has three paths: browser OAuth (default), API key (claude auth login --console), or SSO (claude auth login --sso)
• claude doctor is the verification checkpoint -- if it passes, Claude Code is ready

The problem

Installing a coding agent usually means wrangling language runtimes, compiling native extensions, and debugging environment variables before you even get to a prompt. Claude Code's installer handles the entire stack in one shot. The goal is to go from zero to a working agent in under two minutes.

Options & when to use each

Setup path	Good for	Costs you	When to pick it
Shell installer (curl | bash)	macOS, Linux, WSL2	None -- handles everything	Most users, most of the time
Homebrew (brew install --cask claude-code)	macOS users who manage everything through brew	Requires Homebrew already installed	macOS users already on brew
PowerShell installer	Windows native	Requires PowerShell, some Windows-specific path quirks	Windows users who don't use WSL
winget	Windows native	Requires winget (included in Windows 11, installable on Windows 10)	Windows users who prefer package managers

For this course, we use the shell installer. It's the fastest path and works on every Unix platform we'll cover.

Auth path	Good for	When to pick it
Browser OAuth (claude first run)	Personal use, quick setup	Your first time using Claude Code. Opens a browser, you sign in with your Anthropic account, done
API key (claude auth login --console)	Headless servers, CI/CD, Docker	You're on a machine without a browser, or you're scripting Claude Code in a pipeline
SSO (claude auth login --sso)	Enterprise deployments	Your organization uses Anthropic's enterprise SSO. You'll need your org's SSO URL

Build it

Step 1: Install

On macOS, Linux, or WSL, use the standard shell installer. This script automatically detects your environment and installs the correct binary.

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

On Windows (PowerShell, run as administrator):

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

Or on macOS with Homebrew:

brew install --cask claude-code

Or on Windows with winget:

winget install Anthropic.ClaudeCode

The installer detects your OS and handles dependencies automatically. On macOS and Linux it installs the Claude Code binary and any required dependencies. On WSL2 it works the same as native Linux.

After the installer finishes, verify the binary is on your PATH:

claude --version

You should see v2.x or higher. If you get command not found, restart your shell or source your shell config:

source ~/.bashrc   # or ~/.zshrc on macOS

Step 2: Authenticate

Option A: Browser OAuth (recommended for first-time setup)

Run Claude Code with no arguments. It detects no existing authentication and opens your browser:

claude

Sign in with your Anthropic account. The browser redirects back to the terminal, and Claude Code stores the token. You're authenticated.

Option B: API key (for headless or CI/CD)

claude auth login --console

This prompts for your API key. Paste it at the prompt. The key is stored securely -- never committed to git.

Option C: Enterprise SSO

claude auth login --sso

You'll be prompted for your organization's SSO URL. Claude Code opens a browser to complete the SSO flow.

Step 3: Verify everything works

After installation, run diagnostic checks to confirm the agent is properly authenticated and system dependencies are satisfied.

# Check authentication status
claude auth status

# Run the health check
claude doctor

claude doctor checks that the binary is installed correctly, the auto-updater is configured, and no broken dependencies are detected. If it passes, Claude Code is ready.

If claude doctor reports issues, the most common fixes:

• Auto-updater not configured: run claude update to get the latest version
• Authentication expired: re-run your auth command (claude auth login --console or the OAuth flow)
• Missing dependencies: the installer should have caught these, but on some Linux distributions you may need to install node manually

Step 4: Run a real query, not a hello-world

Test the agent's ability to execute shell commands and parse output. A practical command confirms both network connectivity and local execution rights.

claude -p "What is the current date in ISO 8601 format? Use only the date command, no markdown."

If the response is a valid ISO 8601 date string, authentication is working and Claude Code can execute shell commands. That's the baseline for everything that follows.

Step 5: Keep it updated

Ensure you are running the latest version of the CLI. The built-in auto-updater handles self-updating without needing external package managers.

claude update

Claude Code v2.x has a built-in auto-updater. Run claude update to get the latest version. claude doctor will tell you if your version is out of date.

What goes wrong

Mistake	How you notice it	The fix
claude: command not found after install	The shell can't find the binary	source ~/.bashrc (or ~/.zshrc). The installer adds to PATH, but the current shell session doesn't know about it until you re-source
OAuth flow fails to open a browser	claude hangs waiting for browser auth	You're on a headless server. Use claude auth login --console instead and enter your API key
API key exposed in shell history	You typed claude auth login --console and pasted the key, but it showed up in .bash_history	The --console flag reads the key from stdin, not as a command argument. Your key won't appear in history. If you accidentally passed it as an argument, clear your shell history immediately
claude doctor reports version below v2.x	Features from this course don't work	Run claude update to get the latest. If the installer gave you an old version, re-run the install script
Windows PowerShell: iex blocked by execution policy	`irm ...	iex` fails with a security error
WSL: browser doesn't open for OAuth	The OAuth flow tries to open a browser inside WSL	WSL2 supports GUI apps on Windows 11. If you're on Windows 10, use claude auth login --console with an API key instead

Confirm it worked

Run through this final checklist to guarantee your local environment is fully configured. Passing these checks means you are ready for the core curriculum.

# 1. Verify the install
claude doctor

# 2. Check your auth status
claude auth status

# 3. Confirm the version is v2.x+
claude --version

# 4. Run a real query that exercises shell access
claude -p "List the 5 largest files in my home directory, sorted by size. Use du and sort, output as plain text."

If step 4 returns actual file names and sizes (not an error or a refusal), Claude Code is installed, authenticated, and has working shell access. That's the baseline for everything that follows.

Next: Print Mode -- Your First Real Task -- one-shot mode for scriptable tasks, controlling tool access, and output formats.