Claude Code CLI: Complete Tutorial and Best Practices

Claude Code is Anthropic's official command-line interface for AI-assisted development. Unlike browser-based AI assistants, Claude Code lives in your terminal - exactly where developers spend most of their time.

This tutorial covers everything from installation to advanced workflows. You'll learn how to use Claude Code effectively, integrate it with voice input, and establish best practices for AI-assisted development.

What is Claude Code?
Installation Guide
Basic Usage
Core Commands
File Operations
Advanced Features
Voice Integration with Vocoding
Best Practices
Troubleshooting
Tips and Tricks

What is Claude Code?

Claude Code is a terminal-based AI assistant that can:

Read and write files in your codebase
Execute shell commands (with your permission)
Understand project context across multiple files
Help with complex coding tasks like refactoring, debugging, and code documentation
Search and navigate large codebases

Why Terminal-Based?

Developers live in the terminal. By bringing AI assistance directly to the command line, Claude Code:

Reduces context switching - no browser tabs needed
Integrates with existing workflows - pipes, scripts, automation
Handles file operations naturally - read, write, diff
Maintains session context - remembers what you've discussed

Claude Code vs. ChatGPT vs. Cursor

Feature	Claude Code	ChatGPT	Cursor
File access	Direct	Copy/paste	Direct
Shell execution	Yes	No	Limited
Interface	Terminal	Browser	IDE
Context window	Large	Varies	Medium
Code indexing	Yes	No	Yes
Voice input	Via Vocoding	No	No

Installation Guide

Prerequisites

macOS 10.15+, Windows 10+, or Linux
Node.js 18+ (recommended)
An Anthropic API key

Step 1: Install via npm

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

Or using Homebrew on macOS:

brew install anthropic/tap/claude-code

Step 2: Configure API Key

claude config set api-key sk-ant-your-key-here

Or set it as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Add to your shell profile (.zshrc or .bashrc) for persistence.

Step 3: Verify Installation

claude --version
claude hello

You should see Claude respond in your terminal.

Step 4: Configure Your Editor

Tell Claude which editor you prefer:

claude config set editor "code"  # VS Code
claude config set editor "cursor"  # Cursor
claude config set editor "vim"    # Vim

Basic Usage

Starting a Session

Navigate to your project directory and start Claude:

cd ~/projects/my-app
claude

Claude now has context about your project structure.

Your First Conversation

You: What files are in this project?

Claude: Let me check the project structure...

[Lists files and directories]

This appears to be a Next.js project with TypeScript. I can see:
- src/app/ - Application routes
- src/components/ - React components
- src/lib/ - Utility functions
...

Asking for Help

You: I need to add user authentication. Where should I start?

Claude: Based on your project structure, I recommend:

1. Create an auth utility in src/lib/auth.ts
2. Add protected route middleware
3. Create login/signup pages in src/app/(auth)/

Would you like me to create the initial files?

Exiting

Type exit, quit, or press Ctrl+D to end the session.

Core Commands

Reading Files

You: Show me the contents of src/app/page.tsx

Claude: [Displays file contents with syntax highlighting]

Or be more specific:

You: Show me lines 50-75 of src/lib/api.ts

Writing Files

You: Create a new file src/hooks/useUser.ts with a hook that fetches user data

Claude: I'll create that hook for you.

[Creates file]

Created src/hooks/useUser.ts with:
- useUser hook that fetches from /api/user
- Loading and error states
- TypeScript types

Editing Existing Files

You: In src/components/Button.tsx, add a loading prop that shows a spinner

Claude: I'll modify the Button component to add loading state.

[Shows diff]

Apply these changes? (y/n)

Running Commands

You: Run the tests

Claude: I'll run the test suite.

[Executes: npm test]

[Shows output]

3 tests failed. Would you like me to analyze the failures?

Searching

You: Find all files that import from @supabase/supabase-js

Claude: Searching the codebase...

Found 12 files:
- src/lib/supabase.ts
- src/app/api/auth/route.ts
- src/hooks/useAuth.ts
...

File Operations

Creating Multiple Files

You: Create a complete CRUD API for blog posts with these routes:
- GET /api/posts
- GET /api/posts/[id]
- POST /api/posts
- PUT /api/posts/[id]
- DELETE /api/posts/[id]

Claude: I'll create the API routes with proper TypeScript types.

Creating:
1. src/app/api/posts/route.ts
2. src/app/api/posts/[id]/route.ts
3. src/types/post.ts

[Creates files with full implementation]

Refactoring Across Files

You: Rename the User type to AuthUser throughout the entire codebase

Claude: I'll search for User type usage and rename to AuthUser.

Found 23 occurrences in 8 files:
- src/types/index.ts
- src/hooks/useAuth.ts
- src/components/Profile.tsx
...

Apply all changes? (y/n)

Generating from Existing Code

You: Look at src/lib/database.ts and generate TypeScript interfaces for all the database functions

Claude: Analyzing database.ts...

Here are the interfaces:

[Generates complete TypeScript interfaces]

Should I create these in src/types/database.ts?

Advanced Features

Project Context

Claude Code indexes your project for better understanding:

You: /index

Claude: Indexing project... Done.

Indexed 156 files. I now have deeper context about:
- Your module structure
- Import relationships
- Type definitions
- Common patterns

Multi-File Analysis

You: Analyze the authentication flow from login to protected route

Claude: Tracing the auth flow...

1. Login form (src/app/login/page.tsx)
   - Calls signIn() from useAuth hook

2. Auth hook (src/hooks/useAuth.ts)
   - POST to /api/auth/login
   - Stores token in localStorage

3. API route (src/app/api/auth/login/route.ts)
   - Validates credentials
   - Issues JWT

4. Middleware (src/middleware.ts)
   - Checks token on protected routes
   - Redirects to /login if invalid

[Identifies issues]
There's a potential issue: the middleware doesn't validate token expiration...

Code Review

You: Review my last commit for issues

Claude: Analyzing changes from commit a1b2c3d...

Issues found:

1. **Security** (src/app/api/users/route.ts:45)
   Missing input validation on user ID

2. **Performance** (src/hooks/useData.ts:23)
   This effect runs on every render - add dependencies

3. **Type Safety** (src/lib/utils.ts:67)
   Using 'any' type - should be typed properly

Would you like me to fix these issues?

Git Integration

You: What changed since yesterday?

Claude: [Runs git log and diff]

Since yesterday (2 commits):

1. "Add user profile page" - John
   - New: src/app/profile/page.tsx
   - Modified: src/components/Header.tsx

2. "Fix auth redirect" - Jane
   - Modified: src/middleware.ts

Would you like details on any commit?

Testing

You: Write unit tests for src/lib/validators.ts

Claude: I'll analyze the validators and create comprehensive tests.

[Creates tests with:]
- Valid input cases
- Invalid input cases
- Edge cases
- TypeScript type checking

Created: src/lib/__tests__/validators.test.ts

Run tests with: npm test validators

Voice Integration with Vocoding

Typing long prompts is slow. Vocoding lets you speak naturally and paste optimized prompts into Claude Code.

Why Voice + Claude Code?

Voice input is the fastest way for developers to interact with AI coding tools. Learn more about the voice-to-code development approach.

Speed: Speak complex requests in seconds
Context: Natural speech captures more detail
Flow: Stay in the terminal without switching to type
Accuracy: Vocoding's specialized agents optimize prompts for AI tools

The Workflow

Press your Vocoding hotkey (e.g., Ctrl+Shift+Space)
Speak your intent naturally:

"Create a custom hook for managing form state with validation using Zod. It should handle nested objects, show field-level errors, and support async validation for checking if a username is taken."
Vocoding transcribes and optimizes your speech
Paste into Claude Code (Cmd+V)
Claude executes your request

Example Voice Prompts for Claude Code

Feature Development:

"Add a commenting system to blog posts. Users should be able to add, edit, and delete their own comments. Include nested replies up to 3 levels deep. Use the existing auth system for user identification."

Debugging:

"I'm getting a hydration mismatch error on the dashboard page. It happens when the user has notifications. The server shows 5 notifications but the client shows 3. Help me trace where the mismatch occurs."

Refactoring:

"The user service file is 500 lines and handles too many things. Split it into separate services for user crud, user preferences, and user notifications. Keep the same public API so we don't break existing imports."

Learning:

"Explain how the middleware chain works in this Next.js project. I don't understand how the auth check happens before the route handler. Walk me through the request lifecycle."

Setting Up Vocoding for Claude Code

Download Vocoding from vocoding.com
Set your preferred hotkey
Select "Claude Code" as your target preset
Start speaking your prompts

Vocoding's Claude Code preset (see how Vocoding works):

Formats prompts for CLI context
Includes terminal-specific instructions
Optimizes for multi-file operations

Get Vocoding - Voice input for Claude Code.

Best Practices

1. Start Sessions in Project Root

cd ~/projects/my-app
claude

This gives Claude maximum context about your project.

2. Index Large Projects

For projects with 100+ files:

You: /index

Claude: Indexing... This helps me understand your codebase better.

3. Be Specific About Intent

Instead of:

"Fix the bug"

Try:

"The login form doesn't validate email format before submission. Add client-side validation that checks for valid email format and shows an error message below the input field."

4. Use Incremental Changes

Don't ask for everything at once:

"First, show me the current implementation"
"Now suggest improvements"
"Apply change #2 only"
"Add tests for that change"

5. Review Before Applying

Always review diffs before confirming:

Claude: Here are the proposed changes:

[Shows diff]

Apply these changes? (y/n)
You: Let me review... Yes, apply.

6. Maintain Conversation Context

Build on previous messages:

You: Add a user profile component

Claude: [Creates component]

You: Now add a form for editing the profile

Claude: [Uses context from previous message]

You: Add validation to that form

Claude: [Knows which form you mean]

7. Use Git Alongside Claude

Commit frequently so you can revert if needed:

You: Make these changes to the auth system

[Claude makes changes]

You: /run git diff

[Review changes]

You: /run git commit -m "Refactor auth system"

8. Leverage File References

Be explicit about which files:

You: In src/lib/api.ts, add retry logic to the fetch wrapper. Use the error types from src/types/errors.ts.

Troubleshooting

"Command not found: claude"

Solution: Ensure npm global bin is in PATH:

export PATH="$PATH:$(npm config get prefix)/bin"

Add to your shell profile.

"API key invalid"

Solution: Verify your key:

claude config get api-key

Re-set if needed:

claude config set api-key sk-ant-your-key

"Rate limit exceeded"

Solution: Wait a few minutes, or check your Anthropic usage dashboard for quota.

"File too large to read"

Solution: Ask for specific sections:

You: Show me the first 50 lines of that file

You: Show me the function named handleSubmit

"Context too long"

Solution: Start a new session for unrelated tasks:

You: exit

[Start new session]

claude

Slow Response Times

Solutions:

Index the project: /index
Be more specific about files needed
Check your internet connection
Start a fresh session if context is bloated

Tips and Tricks

Tip 1: Quick Commands

You: /help - Show available commands
You: /clear - Clear conversation history
You: /exit - Exit the session
You: /index - Index the project
You: /run <cmd> - Run a shell command

Tip 2: Use Natural Language for Git

You: Show me what changed in the last week
You: Who wrote the auth module?
You: What commits mentioned "fix"?

Tip 3: Generate Boilerplate Fast

You: Create a Next.js API route template I can reuse for CRUD operations

Tip 4: Learn From Your Codebase

You: What patterns does this codebase use for error handling?
You: How is state management done here?
You: Show me examples of custom hooks in this project

Tip 5: Automate Repetitive Tasks

Create shell aliases:

alias ccr="cd ~/projects/my-app && claude"
alias cctest="claude -c 'run npm test'"

Tip 6: Use Claude for Documentation

You: Generate API documentation for all routes in src/app/api/

You: Create a README for the hooks directory

You: Document the database schema based on the Prisma file

Tip 7: Multi-Session Workflow

Run multiple Claude sessions for different concerns:

Terminal 1: Feature development
Terminal 2: Test writing
Terminal 3: Documentation

Tip 8: Export Conversations

You: /export

[Saves conversation as markdown for future reference]

Tip 9: Use With Voice for Speed

Pair with Vocoding for ultimate speed:

Speak your complex request into Vocoding
Paste into Claude Code
Review and confirm changes
Repeat

This workflow handles complex prompts 3x faster than typing.

Tip 10: Project-Specific Instructions

Create .claude file in project root:

name: My Project
context: |
  This is a Next.js 14 project with TypeScript.
  Use Tailwind CSS for styling.
  Follow existing patterns in src/components.
  Write tests for all new code.

Claude reads this for project-specific context.

Quick Reference

Essential Commands

Command	Action
`claude`	Start session
`exit`	End session
`/help`	Show help
`/index`	Index project
`/clear`	Clear history
`/run <cmd>`	Execute command

Common Prompts

Create:

"Create a [component/hook/api route] for [purpose]"

Modify:

"In [file], add/change/remove [what]"

Debug:

"I'm seeing [error]. Here's the context: [details]"

Review:

"Review [file/commit] for [concerns]"

Explain:

"Explain how [feature/flow] works in this codebase"

Conclusion

Claude Code represents a new paradigm in AI-assisted development. By living in the terminal where developers work, it eliminates the friction of copy-pasting code between browser and editor.

Combined with voice input through Vocoding, you can express complex coding intentions naturally and have them executed immediately. This is the future of development workflows.

Start today:

Install Claude Code
Configure your API key
Try basic file operations
Add voice input with Vocoding
Build your personalized workflow

Resources

Questions about Claude Code? Join our community for help.

Table of Contents