Claude Not Working in Terminal: Fix PATH, Auth, npm, and Network Issues

Overview

Claude not working in terminal usually means one of four layers is failing: command lookup, authentication, network access, or local file access. Start with the command layer before changing project code or reinstalling anything. If command -v claude cannot find the executable, you have a shell or install-path problem. If the command starts but login fails, focus on credentials and browser handoff. If it hangs or times out, check proxy, DNS, VPN, and outbound connectivity. Anthropic documents Claude Code as a terminal-based coding tool in Claude Code official documentation, so terminal behavior depends on your local shell, package manager, and account session as much as the Claude service itself.

Symptoms

The common symptom is simple: typing claude returns a shell error, exits immediately, opens a login flow that never completes, or hangs before showing an interactive prompt. Some users see command-not-found behavior. Others can start Claude but cannot access a project folder, read files, or complete a request. Treat the first visible failure as diagnostic data. A shell error points to installation or PATH. A browser login loop points to authentication. A timeout points to network, proxy, DNS, or service reachability. A file access error points to working directory, permissions, or sandbox behavior.

command -v claude
claude --help
pwd
whoami

Concrete diagnostic example:

$ command -v claude
# no output
$ claude --help
zsh: command not found: claude

Interpretation: the shell cannot find the Claude executable. Do not troubleshoot Anthropic availability yet. Check the install location and PATH first.

$ command -v claude
/Users/alex/.npm-global/bin/claude
$ claude --help
Usage: claude [options] [command]

Interpretation: the binary is visible and can start. If Claude still fails after this point, move to authentication, network, or project-specific checks instead of reinstalling immediately.

Quick decision tree:

command -v claude prints nothing
  -> Fix PATH or reinstall the CLI using your documented install method.

command -v claude prints a path, but claude --help fails
  -> Check Node/npm runtime, permissions, broken package scope, or stale shell.

claude --help works, but login loops or browser handoff fails
  -> Check auth session, browser profile, SSH/container context, and callback restrictions.

claude --help works, but requests hang or time out
  -> Check proxy variables, VPN, DNS, firewall, and Anthropic connectivity from the same terminal.

Claude works in one folder but not another
  -> Check project permissions, mounted paths, symlinks, lockfiles, or repository-specific state.

Why This Happens

Claude in the terminal sits between several moving parts: your shell startup files, Node or package-manager install location, authentication state, project permissions, and network route to Anthropic. A GUI Claude session working in the browser does not prove the CLI is healthy. The terminal may use a different account token, a different proxy, a different DNS path, or a different PATH than your editor. This is the main gotcha: fixing the browser will not fix a missing binary, and reinstalling the CLI will not fix a blocked corporate proxy.

Step 1: Confirm the Claude Command Exists

Start at the shell boundary. If command -v claude prints nothing, your terminal cannot find the executable. That is different from Claude being down or your account failing. Check the npm global binary path only if your install path uses npm, and compare it with echo $PATH. Be aware that npm bin -g is not available in every npm version; if it fails, use npm config get prefix and inspect the bin directory under that prefix, or rely on command -v claude when the command is already visible. Node’s official installation guidance is maintained at Node.js downloads and package manager documentation. If the binary exists but is outside PATH, fix the shell profile rather than reinstalling repeatedly.

command -v claude
which claude
printf '%s\n' "$PATH" | tr ':' '\n'

Step 2: Check Authentication and Account Access

If the command starts but asks you to log in, loops through auth, or exits after browser handoff, focus on credentials. Use the login or auth command exposed by your installed Claude CLI, and complete the flow in the same browser profile you intend to use. Account-specific availability, plan state, and organization restrictions cannot be inferred from the terminal alone. Do not assume an outage or rollout issue without official evidence. If web Claude works but CLI auth fails, capture the CLI output and check whether your terminal is behind a proxy, remote SSH session, container, or restricted browser callback environment.

Step 3: Fix PATH and Shell Profile Drift

Many terminal failures appear after switching shells, installing a new Node version manager, or opening Claude from an editor-integrated terminal. Bash, zsh, fish, VS Code, JetBrains, tmux, and remote shells may load different startup files. If Claude works in one terminal but not another, compare SHELL, PATH, and the detected executable path. This is where competitors often understate the workflow issue: AI CLIs are not single-app installs. They inherit every brittle assumption in your shell bootstrap.

echo "$SHELL"
command -v node
command -v npm
command -v claude
node --version
npm --version

Step 4: Check Node, npm, and Global Install Scope

If your Claude install depends on Node tooling, global package scope matters. A CLI installed under one Node version manager can disappear when another Node version becomes active. Permission fixes should be narrow: prefer user-level package paths or the package manager’s documented approach. Avoid sudo npm install -g as a default repair because it can create root-owned files that later break updates. My recommendation: use one Node manager per machine for AI CLI tools, document the global binary path, and avoid mixing system Node, Homebrew Node, nvm, and Volta unless you need that complexity.

npm config get prefix
npm root -g
npm bin -g 2>/dev/null || true
ls -la "$(dirname "$(command -v claude 2>/dev/null)")" 2>/dev/null

If npm bin -g returns an error such as Unknown command: "bin", do not treat that as proof Claude is missing. Use the prefix instead:

prefix="$(npm config get prefix)"
printf '%s\n' "$prefix/bin"
ls -la "$prefix/bin" 2>/dev/null

Step 5: Separate Network Failure from CLI Failure

A working executable can still fail when DNS, TLS inspection, VPN, firewall, or a corporate proxy blocks outbound requests. Run a basic connectivity check from the same terminal environment. Do not use a browser result as proof; browsers and terminals often use different proxy settings. If you are on a company network, ask whether Anthropic API or Claude domains are allowed. Anthropic’s developer platform documentation is available at Anthropic official documentation, which is the right source for supported developer integration behavior.

env | grep -i proxy
curl -I https://api.anthropic.com 2>/dev/null | head

How to interpret the connectivity check:

HTTP/2 401, 403, 404, or another HTTP response
  -> The terminal reached Anthropic. The remaining issue is more likely auth, request format, account access, or CLI behavior.

curl: (6) Could not resolve host
  -> DNS failed in this terminal environment. Check DNS, VPN, network filtering, or proxy configuration.

curl: (7) Failed to connect or operation timed out
  -> The route is blocked or unavailable. Check firewall, VPN, proxy, or corporate egress rules.

curl: (35) or certificate-related TLS errors
  -> TLS inspection, custom certificates, or proxy configuration may be interfering.

The curl -I command is not a login test and does not prove your Claude account is valid. It only tells you whether this terminal can reach the Anthropic API endpoint well enough to receive an HTTP-level response.

Step 6: Check Project Permissions and Working Directory

Claude may start normally but fail only inside one repository. That points to local permissions, ignored files, symlinks, repo size, lockfiles, or restricted directories. Move to a simple scratch folder and run the same command. If it works there, the CLI is not generally broken. Check whether the current project lives under a synced folder, protected system path, mounted volume, or container bind mount. Avoid running the terminal as administrator or root just to bypass file errors; that can hide the real permission problem and create new ownership issues.

mkdir -p ~/claude-smoke-test
cd ~/claude-smoke-test
pwd
ls -la
claude --help

Step 7: Reset Carefully Only After Capturing Evidence

A clean reinstall is reasonable after you know the command path, package scope, and auth state. Before removing anything, record the current executable path, Node version, npm prefix, shell, and error text. That gives you a rollback map. Delete only the tool-specific package or configuration documented for your install method. Do not wipe your full npm global directory, shell profile, SSH configuration, or project repository as a troubleshooting shortcut.

command -v claude || true
node --version 2>/dev/null || true
npm --version 2>/dev/null || true
npm config get prefix 2>/dev/null || true
echo "$SHELL"

Platform Notes: macOS, Linux, Windows, and WSL

On macOS and Linux, PATH differences between login shells and app-launched terminals are the most common platform-specific trap. On Windows, distinguish PowerShell, Command Prompt, Git Bash, and WSL. Installing Claude in Windows does not automatically make it available inside WSL, and installing it inside WSL does not guarantee PowerShell can see it. In remote development, also separate local terminal state from the remote host. If Claude fails only inside VS Code Remote SSH, debug the remote machine, not the laptop.

When to Reinstall vs When Not To

Reinstall when the binary is missing, the package manager reports a broken global package, or the executable points to an obsolete toolchain you no longer use. Do not reinstall when the same CLI starts but fails only during login, only on one network, or only in one repository. Those cases are usually auth, proxy, or permission problems. The practical rule: if claude --help works, treat the installation as mostly intact. If command -v claude fails, treat the shell and install path as the first-class problem.

If It Still Fails

If Claude still does not work in terminal, preserve the exact command, full error output, operating system, shell, install method, Node version if relevant, and whether the problem happens in a clean folder. Then check official Anthropic help or status channels from your browser. Avoid posting tokens, project secrets, or private repository content when asking for help. A useful support report separates four facts: command lookup result, authentication state, network environment, and project-specific reproduction. That shortens the path from “Claude is broken” to an actionable failure class.

FAQ

Why does my terminal say claude: command not found?

Your shell cannot find the Claude executable. Check command -v claude, then inspect PATH and the package manager’s global binary directory. If Claude was installed under a Node version manager, confirm that the same Node environment is active in this terminal.

Why does Claude work in the browser but not in terminal?

The browser and terminal use different execution paths. The terminal depends on local installation, PATH, auth tokens, proxy variables, DNS, and file permissions. A working browser session confirms account access only for that browser context.

Should I reinstall Claude immediately?

No. Reinstall only after checking command lookup, auth state, package scope, and network behavior. Reinstalling will not fix a blocked proxy, expired login flow, wrong working directory, or editor terminal environment mismatch.

Can a VPN or proxy break Claude in terminal?

Yes. Terminals often use proxy variables such as HTTP_PROXY, HTTPS_PROXY, or NO_PROXY, while browsers may use system or managed settings. Compare behavior on a trusted network if policy allows.

Why does Claude fail only inside one project?

That usually points to project permissions, mounted folders, protected paths, symlinks, or repository-specific state. Test from a new empty directory. If Claude works there, debug the repository environment rather than reinstalling the CLI.

Is there a guaranteed fix for Claude not working in terminal?

No. The correct fix depends on the failure class: missing command, broken install scope, auth loop, network block, or file permission issue. Capture the exact error before changing configuration.