Claude Code CLI setup

Claude Code is a terminal-based AI coding assistant built by Anthropic. It operates directly in your shell, reads and edits files, runs commands, and integrates with your existing development workflow without requiring a separate IDE or editor. Every plugin, automation, and AI-DLC workflow on the Epic on Azure platform depends on Claude Code as its foundation.

By the end of this tutorial you will have Claude Code installed, authenticated, and verified. You will also understand how to extend it with plugins from the otc-awesome-llm repository.

---

Prerequisites

Before starting, confirm that you have the following:

• Workstation running macOS, Windows (with WSL2 or PowerShell), or Linux
• Node.js 18 or later installed and available on your PATH
• Terminal access (Terminal.app, iTerm2, Windows Terminal, or any shell emulator)
• Anthropic API key or organizational SSO credentials (contact your team lead if you do not have these)
• Network access to npm registry and GitHub (direct or through corporate proxy)

Verify your Node.js version before proceeding:

node --version
# Expected output: v18.x.x or higher (e.g., v20.11.0)

If Node.js is not installed or is below version 18, install it from nodejs.org or use your organization's approved package manager (Homebrew, Chocolatey, or nvm).

---

Installation

Install via npm

The recommended installation method is npm global install:

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

This installs the claude binary globally so it is available from any directory.

Verify installation

Confirm that Claude Code is installed and accessible:

claude --version

You should see version output similar to:

claude-code v1.x.x

Alternative installation methods

If npm global installs are restricted in your environment, you can use npx to run Claude Code without a global install:

npx @anthropic-ai/claude-code

Or install to a project-local directory:

mkdir -p ~/tools/claude-code
cd ~/tools/claude-code
npm init -y
npm install @anthropic-ai/claude-code
# Then add ~/tools/claude-code/node_modules/.bin to your PATH

---

Initial configuration

First-time setup

Launch Claude Code for the first time by running:

claude

On first launch, Claude Code walks you through an interactive setup wizard that covers authentication, default model selection, and permission preferences.

Authentication

Claude Code supports two authentication methods:

API key authentication (individual developers):

claude config set apiKey <your-api-key>

Replace <your-api-key> with your actual Anthropic API key. Never commit this value to version control or share it in documentation.

Organizational SSO (team environments):

If your organization uses SSO, Claude Code will redirect you to your identity provider during first launch. Follow the browser prompts to complete authentication. No manual key configuration is needed.

Setting the default model

Configure which Claude model to use by default:

claude config set model claude-sonnet-4-20250514

Common model options include:

Your organization may have a preferred default. Check with your team lead or the Plugin Catalog for current recommendations.

Configuring permission mode

Claude Code asks for permission before performing actions like editing files or running shell commands. You can configure how permissions work:

# Default: ask before every action
claude config set permissions default

# Auto-approve file reads and safe commands
claude config set permissions auto

# Plan-only mode: Claude explains what it would do without executing
claude config set permissions plan

For new users, start with default mode until you are comfortable with how Claude Code operates. You can always change this later.

---

Basic usage

Starting a session

Launch Claude Code from any directory. It automatically detects the git repository context and reads relevant files:

cd ~/scm/optum-tech-compute/ohemr-ansible-playbooks
claude

You are now in an interactive session. Type your request in plain English.

Asking questions about code

Simply type your question. Claude Code reads the relevant files automatically:

> What does the deploy-epic playbook do?

Claude Code locates the playbook file, reads it, and provides an explanation based on the actual code.

Reading files

Claude Code reads files as needed to answer your questions. You can also ask it to read specific files:

> Read the molecule test for this role and explain what it validates

Making edits

Describe the change you want, and Claude Code suggests edits and applies them with your approval:

> Add a retry block to the database connection task with 3 attempts and 10 second delay

Claude Code shows you the proposed diff before applying it. In default permission mode, you confirm each change.

Running commands

Claude Code can execute shell commands when needed:

> Run the molecule tests for this role and show me the results

In default permission mode, Claude Code shows you the command and asks for approval before executing.

---

Installing plugins

Plugin concept

Plugins extend Claude Code with specialized workflows, domain knowledge, and automation capabilities. They are distributed through the otc-awesome-llm repository and installed via the Claude Code CLI.

A plugin can include:

• Skills -- slash commands that invoke predefined workflows (e.g., /commit, /review-pr)
• Agents -- specialized subagent personas with domain expertise
• Hooks -- automated behaviors that trigger before or after tool calls
• MCP servers -- external tool integrations (Teams, Outlook, Jira)

Installing a plugin

Use the claude plugin install command with the plugin name and registry:

claude plugin install ai-dlc@otc-awesome-llm

This downloads the plugin from the otc-awesome-llm repository and registers it with your Claude Code installation.

Listing installed plugins

View all currently installed plugins:

claude plugin list

Example output:

Installed plugins:
  [email protected]          AI Development Lifecycle methodology
  [email protected] Microsoft Teams integration
  [email protected]           Autonomous repository improvement

Removing a plugin

To uninstall a plugin you no longer need:

claude plugin remove teams-automation

---

Key concepts

Before you begin using Claude Code in your daily work, understand these foundational concepts.

Permission modes

CLAUDE.md files

Claude Code reads CLAUDE.md files to understand project-specific instructions, conventions, and constraints. These files exist at three levels:

• Global (~/.claude/CLAUDE.md) -- personal preferences applied to all sessions
• Repository (CLAUDE.md at repo root) -- project conventions, build commands, architecture notes
• Directory (CLAUDE.md in subdirectories) -- context for specific subsections of a project

When you start a session in a repository, Claude Code reads all applicable CLAUDE.md files and follows their instructions. This is how teams enforce coding standards, documentation conventions, and operational procedures without repeating them in every prompt.

MCP servers

Model Context Protocol (MCP) servers extend Claude Code with external tool integrations. An MCP server runs as a local process and provides Claude Code with additional capabilities such as:

• Sending and reading Microsoft Teams messages
• Querying Jira or GitHub issues
• Accessing internal APIs or databases

MCP servers are configured in .mcp.json files at the project or user level. Plugins from otc-awesome-llm bundle their own MCP configurations.

Hooks

Hooks are automated behaviors that trigger at specific points during a Claude Code session:

• PreToolUse -- runs before Claude Code calls a tool (e.g., validate a file before editing)
• PostToolUse -- runs after a tool call completes (e.g., run linting after a file edit)
• Stop -- runs when Claude Code finishes its response (e.g., auto-commit, notification)

Hooks are defined in .claude/settings.json and are typically managed by plugins rather than configured manually.

---

Verification

Confirm your installation is complete and working by running through these checks.

Check the CLI version

claude --version

Expected: version string with no errors.

List installed plugins

claude plugin list

Expected: a list of plugins (or an empty list if none installed yet).

Run a test session

Start Claude Code in any repository and ask a simple question:

cd ~/scm/optum-tech-compute/ohemr-epic-megadoc
claude

Then type:

> What is this repository about?

Claude Code should read the repository's CLAUDE.md and/or README.md and provide an accurate description. If it responds coherently, your installation is working correctly.

---

Troubleshooting

"command not found" after installation

Symptom: Running claude returns command not found or claude: not found.

Cause: The npm global bin directory is not on your PATH.

Solution:

# Find where npm installs global binaries
npm config get prefix

# Add the bin directory to your PATH (adjust for your shell)
# For zsh (~/.zshrc):
export PATH="$(npm config get prefix)/bin:$PATH"

# For bash (~/.bashrc):
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload your shell
source ~/.zshrc  # or source ~/.bashrc

If you still have issues, try reinstalling:

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

Authentication failures

Symptom: Claude Code returns 401 Unauthorized or Invalid API key.

Cause: API key is missing, expired, or incorrectly configured.

Solution:

1. Verify your API key is set:

   claude config get apiKey
   

2. If empty or incorrect, reset it:

   claude config set apiKey <your-api-key>
   

3. For SSO users, re-authenticate:

   claude auth login
   

4. If problems persist, contact your team lead to verify your API key or SSO access is active.

Plugin installation failures

Symptom: claude plugin install fails with network or registry errors.

Cause: Network connectivity issues, corporate proxy blocking access, or incorrect registry URL.

Solution:

1. Verify network access to GitHub:

   gh auth status
   

2. If behind a corporate proxy, ensure your proxy environment variables are set:

   export HTTPS_PROXY=http://proxy.example.com:8080
   export HTTP_PROXY=http://proxy.example.com:8080
   

3. Verify you have access to the otc-awesome-llm repository:

   gh repo view optum-tech-compute/otc-awesome-llm --json name
   

4. Retry the installation after resolving connectivity issues.

Claude Code hangs or does not respond

Symptom: Claude Code starts but does not respond to input.

Cause: Network timeout reaching the Anthropic API, or a misconfigured model setting.

Solution:

1. Check your network connectivity

2. Reset to a known-good model:

   claude config set model claude-sonnet-4-20250514
   

3. If the issue persists, try running with verbose output to diagnose:

   claude --verbose
   

---

Next steps

Now that Claude Code is installed and configured, continue with these guides:

• AI-DLC Methodology -- Understand the structured AI development lifecycle that governs how the platform team uses AI for engineering work
• Your first AI-DLC project -- Walk through a complete AI-DLC cycle from inception to construction using Claude Code and the AI-DLC plugin
• Plugin Catalog -- Browse the full inventory of available plugins with installation instructions, capabilities, and version compatibility