How to Install Claude Code: npm Setup, Auth & First Run

Steps

1. 01

   Install Claude Code globally via npm

   Run the install command below. npm will download the package and run a short postinstall step (install.cjs) that takes roughly 20 seconds on a typical connection. The -g flag installs the claude binary into your global npm bin directory so it is available from any directory.

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

2. 02

   Verify the install

   After install completes, confirm the binary is on your PATH by checking the version. If the command is not found, see the PATH troubleshooting section below.

   claude --version

3. 03

   Authenticate — Option A: Anthropic account (Claude Pro / Max / Team)

   Run claude with no arguments to start the interactive shell. On first launch it will prompt you to authenticate. Choose the 'Login with Anthropic account' flow. This opens a browser window where you authorize Claude Code against your existing Claude Pro, Max, or Team subscription. Once authorized, account metadata is saved to ~/.claude.json and the OAuth token is stored in your OS keychain (under 'Claude Safe Storage'). Subsequent launches skip the browser step automatically. This is the recommended path if you already pay for Claude at claude.ai.

   claude

4. 04

   Authenticate — Option B: ANTHROPIC_API_KEY

   If you prefer API key authentication (useful for CI, shared machines, or pay-per-token billing), set the environment variable before running. Export it in your shell profile (~/.zshrc, ~/.bashrc, etc.) to make it permanent. Claude Code picks up the key automatically on startup — no interactive login step required.

   export ANTHROPIC_API_KEY="sk-ant-..."
   claude

5. 05

   Run Claude Code interactively

   With no arguments, claude opens a persistent interactive session. You can type multi-line prompts, ask it to edit files, run commands, and use slash commands inside the REPL. Type /help inside the session to see available slash commands. Press Ctrl+C or type /exit to quit.

   claude

6. 06

   Run a one-shot prompt (non-interactive / scripting mode)

   For scripting, CI pipelines, or quick one-off tasks, pass the prompt directly. The -p flag (--print) runs the prompt without entering the interactive shell and prints the result to stdout. You can also pass a prompt as a bare positional argument for convenience.

   # Using the --print flag (non-interactive)
   claude -p "Explain what this repo does"
   
   # Or as a positional argument
   claude "List all TODO comments in src/"

7. 07

   Run Claude Code inside your IDE

   Claude Code is a terminal tool — it runs in any integrated terminal. Open your IDE's built-in terminal (VS Code: Ctrl+`, Cursor: same), navigate to your project directory, and run claude. There is no separate IDE plugin install required. The agent reads and edits files directly from the working directory.

   # Navigate to your project first
   cd /path/to/your/project
   claude

8. 08

   Persist your API key in your shell profile (optional but recommended)

   To avoid exporting the key every session when using API key auth, add the export line to your shell profile. Replace ~/.zshrc with ~/.bashrc if you use bash.

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

Troubleshooting

command not found: claude after npm install -g

npm's global bin directory is not in your PATH. Find it with: npm config get prefix — then append /bin to that path and add it to your PATH. Example for macOS/Linux: add export PATH="$(npm config get prefix)/bin:$PATH" to your ~/.zshrc or ~/.bashrc, then run source ~/.zshrc. On macOS with Homebrew-managed Node, the prefix is often /opt/homebrew.

npm ERR! engine: requires node >=18 (or similar Node version error)

Claude Code requires Node 18 or later. Check your version with node --version. If it is older, upgrade via nvm (nvm install --lts && nvm use --lts) or download directly from nodejs.org. If you have multiple Node versions, make sure the active one is >=18 before re-running the install.

npm install fails with EACCES permission denied on global install

You are trying to write to a system-owned directory. The clean fix is to configure npm to use a user-writable prefix: mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global, then add export PATH="$HOME/.npm-global/bin:$PATH" to your profile. Alternatively, use nvm which installs Node in your home directory and avoids this entirely. Do not use sudo npm install -g as it can corrupt permissions.

Authentication loop — browser opens but Claude Code never recognizes the login

This usually means the callback URL was blocked or the browser closed before the token was written. Try again in a browser that is not blocking redirects. If you are on a headless server or CI environment, switch to ANTHROPIC_API_KEY authentication instead — set the env var and run claude without the interactive auth flow.

MCP server shows as 'pending-approval' and tools are not available

Claude Code requires explicit approval of MCP servers defined in a project's .mcp.json file before it exposes their tools. When prompted inside the interactive session, choose to approve the server. If you accidentally rejected it, run claude mcp reset-project-choices inside the project directory, then restart claude to see the approval prompt again.