CLI AI Coding Assistant Installation, Configuration, and Troubleshooting: A Claude Code Guide

This article uses Claude Code, Anthropic’s command-line coding assistant, as the example. Other tools follow a similar installation process; replace the package name and environment variable names accordingly. Package names, variable names, and parameters in this article are subject to the official documentation, and version changes should be resolved according to official guidance.

1. Before You Begin: Confirm Environment Dependencies

A command-line AI coding assistant runs in the terminal and requires three prerequisites: a Node.js runtime, Git, and a usable terminal.

1. Node.js Runtime

Claude Code requires Node.js 18 or higher. Installing the LTS (Long Term Support) version is recommended because it offers better stability. After installation, open a new terminal window and run:

node -v
npm -v

If node -v outputs v18.x.x or higher, the version is acceptable. npm is installed together with Node.js; as long as it outputs a version number, it is available.

Diagnosis and fixes:

• If the output is command not found or “not recognized,” the system cannot find Node.js. Run the installer again and make sure “Add to PATH” is selected during installation. Windows users need to close and reopen the terminal.
• If the version is lower than 18, download the LTS installer from the official website and install it over the existing version, then run node -v again to confirm.

2. Git Version Control Tool

The coding assistant needs to read code history, inspect changes, and generate diffs. Run the following command to check:

git --version

Output similar to git version 2.x.x is normal. If the command is not found, install Git. Windows users can install Git for Windows, which also provides Git Bash.

3. Terminal Program

The choice of terminal affects only the user experience, not functionality. The table below can help you choose:

Terminal type	Examples	Best for
System terminal	macOS Terminal, Windows PowerShell, Linux GNOME Terminal	Getting started; no additional installation
Editor-integrated terminal	VS Code, Cursor integrated terminal	Working alongside code; daily development
Standalone terminal app	iTerm2, Windows Terminal	Multiple tabs, split panes, or customization

Common shells also differ by system. macOS uses zsh by default, with the configuration file ~/.zshrc. Most Linux distributions use bash by default, with the configuration file ~/.bashrc. Windows users should use PowerShell. The macOS and Linux commands in this article use zsh or bash syntax by default, and Windows commands use PowerShell syntax.

2. Installation and Verification

1. Global Installation

Use npm to install globally. After installation, you can call the claude command directly from any directory:

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

After installation, check the version:

claude --version

If a version number is output, installation succeeded.

2. “Command Not Found”

This usually means npm’s global installation directory is not in PATH. First, check npm’s global path:

npm config get prefix

On macOS and Linux, global commands are located in the bin directory under that path. Check whether PATH contains that directory:

echo $PATH | tr ':' '\n' | grep npm

If there is no output, add the directory to PATH. For example, if the prefix output is /usr/local, add export PATH="/usr/local/bin:$PATH" to your shell configuration file, save it, and reopen the terminal.

On Windows, use the following command to find the executable location:

where.exe claude

If it cannot be found, the npm global directory (usually %APPDATA%\npm) is typically not included in the user environment variables. Add that directory to the user variable Path, then reopen PowerShell.

3. Insufficient Permissions (EACCES or EPERM)

If the installation reports insufficient permissions, using sudo directly or running the installation command as administrator is not recommended. Doing so writes global files into system directories and expands the scope of operations. A safer approach is to change npm’s global directory to a location writable by the current user.

On macOS and Linux:

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

Linux users should replace ~/.zshrc with ~/.bashrc. After writing the change, run source ~/.zshrc or reopen the terminal, then run the installation command again.

On Windows, npm installs to the user directory by default and generally does not require administrator permissions. If installation still fails, check whether the directory is restricted by antivirus software or permission policies.

Enterprise-managed devices often have centralized software installation policies. If you encounter permission restrictions, contact your IT department first to confirm whether installation is allowed; do not attempt to bypass the policy.

4. Temporary Run Without Global Installation

If you only want to try it out without changing the global environment, you can run it temporarily with npx:

npx @anthropic-ai/claude-code --version

npx downloads and runs the package in the current session without writing to the global installation directory.

5. Optional: Accelerated Installation

If network access is slow, you can temporarily switch to an npm registry mirror. Check the current registry first:

npm config get registry

Configure the mirror according to the mirror provider’s documentation, then install:

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

After installation, restore the official registry to avoid continuing to use the mirror for later dependency updates:

npm config set registry https://registry.npmjs.org/
npm config get registry

Confirm that the output is https://registry.npmjs.org/. Mirror sites may sync later than the official registry; if the latest version cannot be found, switch back to the official registry and retry.

3. Configure the API Key

The assistant needs to connect to a cloud AI service, so a valid access credential must be configured. Claude Code reads the environment variable named ANTHROPIC_API_KEY.

1. Get the Key

Sign in to the Anthropic Console, go to the API Keys page, and create a new key. The key is displayed only once after generation, so copy it immediately and store it securely. Keys usually start with sk-ant-.

A key is equivalent to account access permissions. Do not paste it into chat windows, screenshots, documents, or code repositories.

2. macOS and Linux Setup

For a temporary setting that applies only to the current terminal session:

export ANTHROPIC_API_KEY="YOUR_API_KEY"

For a permanent setting, write it to your shell configuration file. Opening the file with an editor and adding the line manually is recommended to avoid the key being recorded in shell history:

nano ~/.zshrc

Add the following line at the end of the file:

export ANTHROPIC_API_KEY="YOUR_API_KEY"

After saving, run source ~/.zshrc or reopen the terminal.

To protect the key, restrict read and write permissions on the configuration file so that only the current user can access it:

chmod 600 ~/.zshrc

When verifying, display only the prefix rather than the full key:

echo "$ANTHROPIC_API_KEY" | cut -c1-7

If the output is sk-ant-, the variable is active. If the output is empty, the variable was not loaded; check whether the configuration file is correct or whether the shell was reloaded.

3. Windows PowerShell Setup

Run the following command in PowerShell to write the key to the current user’s environment variables:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "YOUR_API_KEY", "User")

After this command is written, you need to close and reopen PowerShell for it to take effect. Verify with:

$env:ANTHROPIC_API_KEY.Substring(0, 7)

If the output is sk-ant-, it is configured correctly. If Substring throws an error or the variable is empty, the variable was not set; check whether the command was run in a new window.

A safer approach is to set the user variable through the “System Properties → Environment Variables” graphical interface. This avoids leaving the key in command history.

4. Start and Core Operations

After completing the first three sections, enter a Git repository directory and start the assistant:

cd ~/projects/your-repo
claude

On first launch, the assistant will ask you to log in or confirm the key. It will also ask whether to trust the current directory. Only trust directories that you own and are certain you want to process.