If you’re new to Claude Code, the terminal can feel intimidating. This guide walks you through essential commands and explains exactly what’s happening when Claude Code runs commands on your behalf.

Think of the terminal as a text conversation with your computer. Instead of clicking icons and navigating menus, you type requests and get text responses. The terminal predates graphical interfaces by decades, and it persists because it’s faster for many tasks, enables automation, and provides access to powerful tools with no graphical equivalent.

What is the terminal, really?

The terminal is a program that provides a text-based interface to your computer. When you type a command like ls (list files), you’re running a small program that returns information. Commands are just tiny, focused programs that do one thing well.

The terminology confuses newcomers because terminal, shell, console, and command line are often used interchangeably. The practical distinction: the terminal is the window you type into, while the shell is the program inside that interprets your commands. When someone says “open your terminal” or “use the command line,” they mean the same thing for everyday purposes.

Common shells include bash (the most widely used, standard on Linux), zsh (default on macOS since 2019, very similar to bash), and PowerShell (Microsoft’s modern shell for Windows). Basic commands work identically across bash and zsh, and you rarely need to think about which shell you’re using.

The “You Are Here” mental model

The terminal always operates from a specific location in your file system: your working directory. The command pwd (print working directory) shows where you are, like the “You Are Here” arrow on a mall directory. The command cd (change directory) moves you around. Every operation happens relative to your current location unless you specify an absolute path.

When you type ls, you’re asking “what’s in this folder?” When you type cd Documents, you’re walking into the Documents folder. The symbol .. means “parent directory” (one level up), and ~ is shorthand for your home folder.

Addressing the fear factor

The terminal’s minimalist appearance intimidates beginners. No buttons, no undo, no “Are you sure?” prompts. This fear is somewhat justified: commands like rm (remove) permanently delete files without sending them to trash. But here’s the reality: you only need about 10 commands for daily use, and the safe commands vastly outnumber the dangerous ones.

Commands like ls, cd, pwd, cat, and grep are purely read-only. They cannot damage anything. The risky commands involve deletion (rm), system modification (chmod, sudo), or disk operations. When using Claude Code, you’ll see exactly what commands it wants to run and must approve anything potentially destructive.

Essential commands every beginner should know

These commands form the foundation of terminal literacy. Master these, and you’ll understand what Claude Code is doing when it explores your codebase.

Navigation: Finding your way around

pwd prints your current location. Run it first to orient yourself.

$ pwd
/home/username/projects

ls lists what’s in the current directory. The -la flags show hidden files (those starting with .) in detailed format:

$ ls -la
total 24
drwxr-xr-x  3 user user 4096 Jan 15 10:30 .
drwxr-xr-x 18 user user 4096 Jan 14 09:00 ..
-rw-r--r--  1 user user  220 Jan 15 10:30 .gitignore
drwxr-xr-x  2 user user 4096 Jan 15 10:30 src
-rw-r--r--  1 user user 1024 Jan 15 10:30 package.json

cd changes your location. Use cd .. to go up one level, cd ~ to jump home, and cd - to toggle back to your previous location:

cd Documents          # Enter Documents folder
cd ../..              # Go up two levels
cd ~/projects/myapp   # Jump to absolute path using home shortcut

File operations: Creating and managing files

mkdir creates directories. Use -p to create nested folders in one command:

mkdir projects
mkdir -p projects/web/frontend/components

touch creates empty files or updates timestamps on existing ones:

touch newfile.txt
touch index.js styles.css  # Create multiple files

cp copies files. Add -r for directories (recursive copy):

cp original.txt backup.txt
cp -r src/ src-backup/

mv moves or renames files. There’s no separate rename command:

mv oldname.txt newname.txt   # Rename
mv file.txt ~/Documents/     # Move to Documents

rm removes files permanently. Be careful with this one. Use -i for confirmation prompts while learning:

rm unwanted.txt          # Delete file (no confirmation!)
rm -i important.txt      # Ask before deleting
rm -r foldername/        # Delete folder and contents

Viewing file contents

cat displays an entire file at once. Best for short files:

cat config.json

less provides paginated viewing for longer files. Navigate with arrow keys, space for next page, q to quit:

less longfile.log

head and tail show the first or last lines. The -n flag specifies how many:

head -n 20 file.txt    # First 20 lines
tail -n 50 server.log  # Last 50 lines
tail -f app.log        # Follow file in real-time (great for logs)

Finding things

grep searches for text patterns inside files. Claude Code relies heavily on this:

grep "error" logfile.txt           # Find lines containing "error"
grep -i "warning" app.log          # Case-insensitive search
grep -r "TODO" ./src/              # Search recursively in src folder
grep -n "function" script.js       # Show line numbers

find locates files by name or attributes:

find . -name "*.txt"               # Find all .txt files
find /home -name "config"          # Find files named "config"
find . -type f -name "*.log"       # Find only files (not directories)

which reveals where a command lives:

which python    # Shows /usr/bin/python or similar
which node

Understanding paths

Paths come in two flavors. Absolute paths start from the root (/ on Mac/Linux, C:\ on Windows) and work from anywhere: /home/user/projects/app.js. Relative paths are based on your current location: ./src/components/Button.js or ../config/settings.json.

Special path symbols to memorize:

• .: current directory
• ..: parent directory (one level up)
• ~: home directory
• /: root directory (top of filesystem)

Claude Code: CLI commands and interaction

Claude Code is Anthropic’s agentic coding assistant that lives in your terminal. It understands your codebase contextually and executes commands on your behalf, with your permission.

Installation

Claude Code requires Node.js 18 or later. Install it via npm:

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

After installation, navigate to any project and type claude to start. First-time users authenticate via browser.

Essential CLI flags

Piping content to Claude Code enables powerful workflows:

cat error.log | claude -p "explain these errors"
git diff | claude -p "review these changes"

Slash commands inside Claude Code

Once you’ve started an interactive session with claude, slash commands control the experience:

Session management:

• /help: Lists all available commands
• /clear: Wipes conversation history for a fresh start
• /compact: Summarizes the conversation to free up context window
• /exit or /quit: Quit Claude Code

Context and configuration:

• /init: Generates a CLAUDE.md file describing your project
• /config: Opens settings interface
• /model: Switch between AI models mid-session
• /permissions: View and adjust permissions

Development tools:

• /review: Request a code review
• /doctor: Diagnose installation problems
• /cost: Show token usage for current session

The /compact command deserves special mention: when conversations grow long, Claude may start “forgetting” earlier context. Running /compact focus on the authentication code summarizes everything while preserving what matters.

Reading Claude Code’s output

When Claude Code runs commands, you’ll see clear output like:

⏺ Running: git status
  Description: Shows working tree status

The tool requests permission before executing anything that modifies files or runs potentially impactful commands. You can accept once, accept always for the session, or deny. Always read what Claude Code wants to do before approving.

Key keyboard shortcuts within Claude Code:

• Escape: Stop Claude’s current generation
• Ctrl+C twice: Force exit
• Tab: Toggle extended thinking display
• Shift+Tab: Cycle through modes

What commands does Claude Code actually run?

Understanding what happens behind the scenes helps you learn and builds confidence. Here’s what Claude Code executes for common tasks.

File discovery

Rather than running raw find or ls commands, Claude Code uses built-in tools optimized for speed and safety. When searching for files, it uses glob patterns:

**/*.js           All JavaScript files recursively
src/**/*.ts       TypeScript files in src/
*.{json,yaml}     JSON and YAML files in current directory
test/**/*test.js  Test files matching pattern

For directory listings, Claude Code’s internal tools provide structured output. You may occasionally see standard ls or ls -la when Claude needs a quick overview.

Content searching

Claude Code’s search capabilities are powered by ripgrep (rg), a fast search tool. When you ask Claude to find something, it might run:

rg "function authenticate" --type js     # Find in JavaScript files
rg "TODO" -c                              # Count occurrences
rg "error" -i -C 2                        # Case-insensitive with context lines
rg "import.*React" --glob "*.tsx"        # Find React imports in TSX files

Claude Code uses ripgrep rather than traditional grep for dramatic performance improvements on large codebases.

File reading and modification

For reading files, Claude Code uses its built-in Read tool rather than cat. This provides line numbers and handles special files like images, PDFs, and notebooks. For modifications, the Edit tool makes surgical changes rather than using sed or awk:

{
  "file_path": "/path/to/file.ts",
  "old_string": "oldFunctionName",
  "new_string": "newFunctionName",
  "replace_all": true
}

This approach prevents accidental overwrites and provides clear diffing.

Git commands

Git is where you’ll see the most bash commands. Claude Code runs these frequently:

# Checking state (often run in parallel)
git status                    # What's changed?
git diff                      # Unstaged changes
git diff --staged             # Staged changes
git log --oneline -10         # Recent commits

# Making changes
git add .                     # Stage all changes
git commit -m "message"       # Commit with message
git branch --show-current     # Current branch name

# Working with remotes
git push origin main
git pull origin main

Before committing, Claude Code typically runs git status, git diff, and git log in parallel to understand the full picture.

Package managers and build tools

Development workflows involve frequent package manager commands:

# Node.js/npm
npm install                   # Install dependencies
npm run build                 # Build project
npm run dev                   # Start development server
npm test                      # Run tests

# Python/pip
pip install -r requirements.txt
pytest                        # Run tests

# Other ecosystems
cargo build                   # Rust
go build                      # Go
yarn install                  # Yarn

System and process commands

Occasionally Claude Code checks system state:

which python          # Find where Python is installed
env                   # List environment variables
ps                    # Check running processes
file document.pdf     # Determine file type
wc -l bigfile.txt     # Count lines

Cross-platform considerations

The terminal experience varies across operating systems.

macOS users

macOS uses zsh by default since Catalina (2019). Open Terminal via Cmd + Space, type “Terminal”, and press Enter. For enhanced features, many developers prefer iTerm2, which offers split panes, better search, and extensive customization.

Linux users

Most distributions default to bash and include terminals like GNOME Terminal or Konsole. Installation mirrors macOS.

Windows users

Windows offers multiple approaches:

Option 1: WSL (Recommended for full compatibility) WSL (Windows Subsystem for Linux) runs a complete Linux environment within Windows:

# In PowerShell as Administrator
wsl --install

# After restart, in the new Ubuntu terminal:
npm install -g @anthropic-ai/claude-code

Option 2: Git Bash (Simpler setup) Git Bash provides Unix-like commands and is supported by Claude Code. Install Git for Windows and use the included Git Bash terminal.

Option 3: Native PowerShell Claude Code works in PowerShell, though some commands differ from their Unix equivalents.

Command equivalents across platforms

One critical difference: Linux is case-sensitive (File.txt and file.txt are different files), while Windows and macOS (by default) are not.

Practical safety tips

Decoding error messages

“command not found” means the command doesn’t exist or isn’t in your PATH. Check spelling (commands are case-sensitive on Linux), verify the program is installed, or use which programname to locate it.

“permission denied” indicates you lack access rights. For scripts, chmod +x script.sh adds execute permission. For system operations, sudo provides administrator access, but use it carefully.

“No such file or directory” means your path is wrong. Double-check the location with pwd and ls.

Commands that need caution

The most dangerous command is rm -rf:

• rm = remove
• -r = recursive (deletes everything inside directories)
• -f = force (no confirmation prompts)

Never run rm -rf / or rm -rf ~. These would delete your entire system or home folder. Claude Code asks permission before running deletion commands and blocks particularly risky patterns.

Similarly, sudo (superuser do) grants administrator privileges. Only use it when installing system packages or modifying protected files, and always read what follows sudo carefully.

Keyboard shortcuts that save you

Tab completion is transformative. Type the first few characters of any file, folder, or command and press Tab. The shell completes it automatically or shows options if there are multiple matches. This prevents typos and accelerates navigation dramatically.

When something looks scary

If terminal output seems alarming:

1. Don’t panic. Most output is informational.
2. Press Ctrl+C to stop any running command.
3. Read the error carefully. It usually explains what went wrong.
4. Ask Claude Code for help describing what happened.

Claude Code itself has guardrails: it shows you exactly what commands it wants to run, requests permission for anything potentially impactful, and allows you to deny risky operations. The /permissions command lets you review and adjust what tools Claude Code can use.

Getting started checklist

Ready to begin? Here’s your path forward:

1. Open your terminal. Terminal.app on Mac, your preferred Linux terminal, or WSL/Git Bash on Windows.
2. Try safe commands. Run pwd, ls, cd Documents, cd .., ls -la to get comfortable navigating.
3. Install Claude Code. Use npm install -g @anthropic-ai/claude-code.
4. Run claude doctor. Verify your installation is healthy.
5. Start Claude Code in a project. Navigate to a code folder and type claude.
6. Run /init. Let Claude Code create a project description.
7. Ask Claude Code to explain. Request explanations for anything you don’t understand.

The terminal rewards investment quickly. Within a few hours of practice, navigation becomes instinctive. Within a few days, you’ll wonder how you worked without it. And with Claude Code as your pair programmer, you have a guide explaining every step of the journey.