Guides
Getting started

Claude Code CLI setup guide

Install Claude Code CLI on your computer — step-by-step for Mac, Windows, and Linux.

Step 0: Three questions before anything else

Ask the user all three of these before doing anything:

1. What operating system are you on?

  • Mac
  • Windows
  • Linux

2. Do you have a Claude Pro, Team, or Enterprise subscription?

Claude Code requires a paid plan. Free accounts won't work.

  • If yes: great, continue.
  • If no: tell them to go to claude.ai/upgrade first. There's no point installing anything without it.

3. Have you used a terminal (command line) before?

This helps you calibrate how much to explain. If they haven't, slow down even more than this guide suggests.

Mac Setup

Open the terminal

Tell them:

  1. Press Command + Space to open Spotlight
  2. Type Terminal
  3. Press Enter

A window with a blinking cursor will appear. That's the terminal. Everything from here gets typed into that window and confirmed with Enter.

Check if Node.js is already installed

Before installing anything, check:

bash
node --version
  • If it prints something like v18.x.x or higher → skip to "Install Claude Code"
  • If it says command not found → continue below

Install Homebrew

Homebrew is a tool that makes installing software on Mac easy. Paste this entire line and press Enter:

bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

What to expect:

  • It will ask for your Mac password. The password won't show as you type — this is normal. Just type it and press Enter.
  • If it mentions installing Xcode Command Line Tools, that's fine. Let it run. It can take a few minutes.

The PATH step — read carefully

When Homebrew finishes, look at the last few lines printed in the terminal. If you see a block that says something like "Next steps" or "Run these commands", it will show you two lines that look like this:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

These lines will be slightly different on every Mac. Copy the exact lines printed on YOUR screen — don't use the ones above.

Paste them into the terminal and press Enter. Without this step, Homebrew won't work.

If you don't see any "next steps" block, that's fine — your Mac didn't need it.

Verify Homebrew works:

bash
brew --version

Should print something like Homebrew 4.x.x. If it says command not found, the PATH step above wasn't completed. Close the terminal, open a new one, and run the two lines again.

Install Node.js

bash
brew install node

This takes a minute or two.

Verify:

bash
node --version

Should print v18.x.x or higher. If it says command not found, close the terminal completely, open a new one, and try node --version again — new installs aren't picked up by already-open windows.

Install Claude Code

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

If you get a "permission denied" error, do this instead — it avoids needing admin rights:

bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zprofile
source ~/.zprofile
npm install -g @anthropic-ai/claude-code

Note: Avoid using sudo npm install — it can cause problems with npm permissions down the line.

Verify:

bash
claude --version

Should print a version number. If it says command not found, close and reopen the terminal and try again.

Log in

bash
claude

This opens Claude Code. Once inside, type:

/login

A browser window should open. Log in with your Claude account.

If the browser doesn't open automatically, look for a URL printed in the terminal. Copy it and paste it into your browser manually.

Once logged in, you'll see a confirmation in the terminal. You're ready. Start typing messages to Claude directly in the terminal.

To exit Claude Code:

/exit

Windows Setup

Open PowerShell

  1. Press the Windows key
  2. Type PowerShell
  3. Click Windows PowerShell (not "ISE", not "x86")

A blue window with a blinking cursor will appear. That's your terminal.

Check if Node.js is already installed

bash
node --version
  • If it prints v18.x.x or higher → skip to "Install Claude Code"
  • If it says 'node' is not recognized → continue below

Install Node.js

  1. Go to https://nodejs.org
  2. Click the button labeled LTS (Long Term Support)
  3. Run the downloaded installer
  4. Click Next through all screens — keep all defaults
  5. On the screen that mentions "Tools for Native Modules": if you see a checkbox, you can leave it unchecked — Claude Code doesn't need it
  6. Click Install, then Finish

Important: After installing, you MUST close PowerShell and open a new one. The existing window won't know Node was installed.

Open a fresh PowerShell (same steps as before) and verify:

bash
node --version

Should print v18.x.x or higher.

Install Claude Code

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

If you get a "permission denied" or "EPERM" error:

  • Close PowerShell
  • Right-click Windows PowerShell in the Start menu
  • Select Run as administrator
  • Try the install command again

Verify:

bash
claude --version

Should print a version number. If it says command not found, close and reopen PowerShell.

Log in

bash
claude

Inside the session, type:

/login

A browser window should open. Log in with your Claude account.

If the browser doesn't open, copy the URL printed in the terminal and paste it into your browser manually.

Once logged in, you're ready.

To exit:

/exit

Linux Setup

Open the terminal

  • Ubuntu/Debian: Press Ctrl + Alt + T
  • Or search "Terminal" in the application menu

Check if Node.js is already installed

bash
node --version
  • If it prints v18.x.x or higher → skip to "Install Claude Code"
  • If it says command not found → continue below

Install Node.js

For Ubuntu/Debian:

bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs

For other distros (Fedora, Arch, etc.) — ask Claude which command to use for your specific distribution.

Verify:

bash
node --version

Install Claude Code

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

If you get a "permission denied" error, configure npm to use a user-writable directory first:

bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

Avoid using sudo npm install -g — it can corrupt npm's global state.

Verify:

bash
claude --version

Log in

bash
claude

Then type:

/login

If the browser doesn't open, copy the URL from the terminal and paste it into your browser.

To exit:

/exit

After setup: Daily use

  • To start Claude Code: open the terminal and type claude
  • Type your message and press Enter
  • Type /help to see all available commands
  • Type /exit to quit
  • Claude can read and edit files, run commands, write code, and search the web — all from the terminal

Common issues

ProblemFix
command not found after installingClose the terminal completely, open a new one, try again
permission deniedOn Mac/Linux: use the npm-global approach above. On Windows: run PowerShell as Administrator
Password doesn't show while typingNormal — terminals hide passwords. Just type it and press Enter
Browser doesn't open for loginCopy the URL printed in the terminal, paste it into your browser
npm: command not foundNode.js didn't install correctly — go back to the Node.js step
Login says "no active subscription"You need a Claude Pro ($20/month), Team, or Enterprise plan at claude.ai/upgrade
Homebrew says command not found after installingThe PATH step was missed — open a new terminal and run the two lines Homebrew printed at the end of its install