Claude CLI Installation Tutorial 2026: macOS, Windows, WSL2 Setup | TeamoRouter

Quick Answer

Claude CLI (Claude Code) installation varies by platform: macOS users install via Homebrew (brew install claude-code), Windows users install via npm inside WSL2 (npm install -g @anthropic-ai/claude-code), and Linux users use npm or the standalone binary. The minimum Node.js version is 18. After installation, configure your API endpoint—either directly to Anthropic's API (requires an API key with overseas payment) or through a unified gateway like TeamoRouter (supports Alipay/WeChat, no VPN needed). Full walkthrough below.

What Is Claude CLI (Claude Code)?

Claude CLI -- officially branded as Claude Code -- is Anthropic's command-line agentic coding tool. It runs in your terminal and can read, write, and refactor code across your entire project, execute shell commands, manage Git operations, and interact with MCP (Model Context Protocol) servers for extended capabilities like database access, web search, and API integration.

Unlike the claude.ai web interface, Claude CLI has direct filesystem access, runs in your shell environment, and operates as an agent: it can plan multi-step tasks, execute them, observe the results, and iterate. It is the primary tool for AI-assisted software development in the terminal, competing with tools like Codex, Cursor CLI, and GitHub Copilot CLI.

Prerequisites

Before installing Claude CLI, make sure your system meets these requirements:

Claude CLI works everywhere Node.js runs, but the best experience is on macOS and Linux. Windows users must install WSL2 first -- native Windows is not supported yet.

Installation: macOS

Option 1: Homebrew (Recommended)

Homebrew provides the simplest installation and update path:

# Install Node.js first (if not already installed)
brew install node@20

# Verify Node.js
node --version  # Should show v20.x.x or later
npm --version   # Should show v10.x.x or later

# Install Claude Code
brew install claude-code

# Verify installation
claude --version

Homebrew handles Node.js as a dependency automatically. Updates: brew upgrade claude-code.

Option 2: npm (Global Install)

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

On macOS, you may need sudo for global npm installs if you installed Node.js via the official installer. Using nvm avoids this: nvm installs global packages in your home directory.

Installation: Windows (via WSL2)

Claude CLI does not support native Windows yet. WSL2 is required.

Step 1: Install WSL2

Open PowerShell as Administrator:

wsl --install

Restart your computer. A Ubuntu terminal will open after restart.

Step 2: Install Node.js inside WSL2

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version
npm --version

Step 3: Install Claude Code

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

For best performance, keep your project files inside the WSL2 filesystem (~/projects/) rather than on the Windows mount (/mnt/c/). Cross-filesystem I/O has overhead that can slow large-scale file operations.

Installation: Linux

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

# Fedora/RHEL
sudo dnf module install nodejs:20
npm install -g @anthropic-ai/claude-code

# Arch Linux
sudo pacman -S nodejs npm
npm install -g @anthropic-ai/claude-code

First-Run Configuration

After installation, configure your API endpoint:

Option A: Direct Anthropic API

export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

Requires an Anthropic account with an overseas payment method.

Option B: TeamoRouter Gateway (Recommended)

export ANTHROPIC_BASE_URL="https://api.teamorouter.com/anthropic"
export ANTHROPIC_API_KEY="tr-your-key-here"

TeamoRouter gives you access to Claude Fable 5, Sonnet 4, Opus 4, GPT-4o, Gemini, and more through a single API Key. Supports Alipay and WeChat Pay for top-ups -- no overseas credit card needed. Provides >99% prompt cache hit rate, dramatically reducing per-token costs.

To persist configuration:

# For zsh (macOS default)
echo 'export ANTHROPIC_BASE_URL="https://api.teamorouter.com/anthropic"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="tr-your-key"' >> ~/.zshrc
source ~/.zshrc

# For bash (Linux default)
echo 'export ANTHROPIC_BASE_URL="https://api.teamorouter.com/anthropic"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="tr-your-key"' >> ~/.bashrc
source ~/.bashrc

Or edit ~/.claude/settings.json:

{
  "apiKey": "tr-your-key",
  "baseUrl": "https://api.teamorouter.com/anthropic"
}

Test Your Setup

echo "Write a Python function that reverses a string" | claude

If you get a proper response, you are all set.

Configuration Comparison: Direct vs Gateway

For more details, see TeamoRouter's AI API gateway.

Troubleshooting Common Installation Issues

"command not found: claude"

The npm global bin directory is not in your PATH:

npm config get prefix
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission errors on global npm install (macOS/Linux)

Use nvm to manage Node.js (installs global packages without sudo):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20
npm install -g @anthropic-ai/claude-code

Node.js version too old

# Install nvm and upgrade
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20
nvm alias default 20

"Authentication failed" on first run

1. Verify the key is complete (no missing characters)
2. Confirm no extra trailing slash on the base URL
3. Check the key has not been revoked in the console
4. Try without a custom base URL to confirm the key works against the official endpoint first

WSL2: file system performance issues

Move your project from Windows filesystem to WSL2 native filesystem:

cp -r /mnt/c/Users/YourName/Projects/my-project ~/projects/my-project
cd ~/projects/my-project
claude

macOS: "Developer cannot be verified" warning

Go to System Settings > Privacy & Security and click Allow Anyway next to the blocked application. This is standard macOS behavior for tools distributed outside the App Store.

Uninstalling and Upgrading

# Uninstall (Homebrew)
brew uninstall claude-code

# Uninstall (npm)
npm uninstall -g @anthropic-ai/claude-code

# Remove all local config
rm -rf ~/.claude

# Upgrade
brew upgrade claude-code      # Homebrew
npm update -g @anthropic-ai/claude-code  # npm

FAQ

Do I need Node.js to use Claude CLI?

Yes. Claude Code is a Node.js application distributed via npm and Homebrew. The minimum version is Node.js 18. You do not need to write JavaScript -- it is just the runtime.

Can I install Claude Code on Windows without WSL?

No. Native Windows support is not yet available. WSL2 is the required and officially supported path for Windows users. The setup takes approximately 10 minutes on a modern machine.

How do I update Claude CLI to the latest version?

brew upgrade claude-code (macOS/Homebrew) or npm update -g @anthropic-ai/claude-code (Linux/npm). Check your version with claude --version.

Can I use Claude CLI without an Anthropic API key?

You can use it with any Anthropic-compatible API endpoint configured via ANTHROPIC_BASE_URL. For example, TeamoRouter provides an Anthropic-compatible endpoint with its own API key format (tr-).

How do I configure Claude Code to use multiple API providers?

Use ~/.claude/settings.json or switch by changing ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY. Tools like the TeamoRouter Client allow hot-swapping providers without manual config editing.

Is the Homebrew installation different from npm?

No functional difference. Homebrew wraps the npm package and handles Node.js dependencies for you. Both install the same claude command.

Does Claude CLI work offline?

No. Claude Code requires a network connection to an API endpoint for every interaction. There is no local model or offline mode.