This guide is for people who are building real things with Claude Code but haven’t spent much time in the terminal. Designers, product managers, founders who have picked up coding recently. If the terminal feels like reading another language, this is the starting point.

What the Terminal Actually Is

Your computer has two ways to interact with it.

The first is what you’re used to: icons, windows, buttons. You click a file to open it. You drag it to the trash to delete it. The computer shows you what’s happening visually.

The second is the terminal. Instead of clicking, you type. Instead of visual feedback, you get text. It’s the same computer doing the same things, just through a different interface.

The terminal can do everything the graphical interface (sometimes called a GUI, or graphical user interface) can do, and usually faster. When Claude Code searches your entire codebase for a function name, it does that in the terminal because searching thousands of files through a visual interface would be painfully slow.

The terminal comes pre-installed on Mac (it’s called Terminal). Tools like VS Code and Cursor have one built in. When you see Claude Code working, it’s using that built-in terminal.

Files, Folders, and Where You Are

Everything on your computer is either a file or a folder. Files have content (code, images, documents). Folders contain files and other folders.

The terminal uses slightly different words. Folders are called directories. Your project is a directory (usually containing many sub-directories). Same concept, different name.

The terminal always has a current location. Think of it like Finder or Windows Explorer: you’re always looking at a specific folder. In the terminal, that location is called the working directory.

When Claude Code opens in your project, the working directory is your project folder. Every command it runs starts from there.

File paths can be relative or absolute. An absolute path starts from the root of your computer, like /Users/yourname/Projects/my-app/src/App.tsx. A relative path starts from wherever you currently are. If your working directory is /Users/yourname/Projects/my-app, then src/App.tsx points to the same file. Most commands Claude Code runs use relative paths, so knowing your current location matters.

If you’re ever unsure which directory you’re in, you can check by running:

pwd

This prints the full path. Something like /Users/yourname/Projects/my-app. Read-only, nothing changes.

To move to a different directory, use cd (change directory):

cd ~/Projects/my-app

The ~/ is a shortcut that means your home folder (usually /Users/yourname on Mac or /home/yourname on Linux). So ~/Projects/my-app expands to the full path automatically.

You can also move up one level with cd ../:

cd ../

The ../ means “the parent directory,” or one folder up from where you currently are. If you’re in /Users/yourname/Projects/my-app/src, running cd ../ takes you back to /Users/yourname/Projects/my-app.

This is how you navigate to your project before starting Claude Code. If Claude Code isn’t finding the files you expect, it might be running from the wrong directory. Use pwd to check, and cd to move to the right place.

Looking Around: What Claude Code Does First

Before Claude Code makes any changes, it looks around. It needs to understand what exists before it can modify anything. The commands it uses for this are all read-only — they cannot break anything.

ls lists the files and folders in the current directory:

ls
ls src/components

Claude Code might run ls before creating a file to confirm it doesn’t already exist. Or look inside a specific folder to understand what’s there.

cat prints the contents of a file:

cat package.json

When Claude Code reads your package.json to understand your project’s dependencies, this is what it’s doing. Reading, not changing.

One thing to keep in mind: cat is read-only, but be cautious if Claude Code tries to cat files that contain secrets, like .env files with API keys or passwords. Those contents will be visible in your terminal session and sent to Claude as context. Treat secret files the same way you’d treat a password: don’t share them unless you understand where they’re going.

grep searches for text inside files:

grep -r "handleSubmit" src/

The -r here is a flag. Flags modify how a command behaves. They usually start with a dash (-) followed by a letter. In this case, -r tells grep to search recursively, meaning it looks through every file in the src/ folder and all its sub-folders. Without -r, it would only search a single file.

You’ll see flags on many commands. ls -l shows files in a detailed list. rm -r deletes directories. Each flag changes the command’s behavior in a specific way. When you see one you don’t recognize, that’s a good time to ask Claude what it does.

This grep command finds every file in src/ that contains the text handleSubmit. Claude Code uses this constantly to find where things are defined and where they’re used.

All of these commands are exploratory. Nothing gets created, moved, or deleted. If you’re unsure whether to approve a command, ls, cat, and grep are safe.

When Claude Code Actually Changes Things

Reading is safe. Everything else deserves attention.

Creating files and directories:

mkdir src/components/forms
touch src/components/forms/LoginForm.tsx

mkdir creates a directory. touch creates an empty file. Low-risk, but worth understanding what’s being created and where.

Moving and renaming:

mv LoginForm.tsx AuthForm.tsx

mv moves or renames a file. After this runs, LoginForm.tsx no longer exists under that name. Renaming in the terminal is just a move with a new name.

Deleting:

rm old-config.ts
rm -r deprecated/

rm deletes files. rm -r deletes entire directories and everything inside them. There is no trash bin. No undo. The file is gone.

Claude Code shouldn’t be deleting things without telling you what and why. If you see rm -rf, verify that you actually want those files removed before approving. If you are unsure, ask Claude what it’s deleting and why.

Running your project’s tools:

Depending on your project, you’ll see Claude Code use different package managers and tools. A package manager handles your project’s dependencies: the external libraries and code your project relies on so you don’t have to build everything from scratch.

The most common ones are npm (for JavaScript/Node.js projects), pip (for Python), gem (for Ruby), and yarn (an alternative to npm). Claude Code will use whichever one your project is set up with. When Claude Code runs npm install or pip install, it’s downloading packages. npm run build tells npm to run a build script defined in your project.

git is version control. It tracks every change to your code over time, like a detailed save history. git add tells git which files to include in your next save. git commit takes those staged files and saves them as a snapshot in the project’s history.

npm install
npm run build
git add . && git commit -m "Add login form"

These commands do real things. npm install downloads packages to your project. git commit saves your changes to version history. When Claude Code runs these, it’s making moves that affect your project’s state.

Reading a Command Before You Approve

You might see more complicated commands from Claude Code. Take the following example:

find . -name "*.test.ts" | grep "auth"

These are actually sequences of simpler commands combined together, a powerful feature of the terminal that lets you compose tools. To understand it, break it down from left to right:

• find . — search starting from the current directory (. means “here”)
• -name "*.test.ts" — find files that end in .test.ts
• | — take the results and feed them to the next command
• grep "auth" — filter those results to only lines containing “auth”

The full command: “Find all test files and show me the ones related to auth.” That’s read-only. Safe to approve.

The | character is called a pipe. It chains commands together: the output of the first becomes the input of the second. You’ll see it often. When you do, read each side separately, then understand what connects them.

Commands to Think Twice About

Most of what Claude Code runs is safe. A few patterns are worth pausing on.

rm -rf on anything important:

rm -rf src/

This deletes the entire src directory instantly. Claude Code will ask you to approve this command, but once you do, there’s no additional safety net from the operating system. No trash bin, no undo. Be sure about this before approving.

sudo:

sudo npm install -g some-package

sudo runs a command as an administrator. It will prompt you for your computer’s password. Claude Code rarely needs this. If you see it, ask Claude why it’s necessary. And don’t type your password into Claude Code’s prompt. If sudo is truly needed, deny the command, then run it yourself directly in your own terminal after Claude explains what it does.

curl piped into bash:

curl is a command that downloads content from the internet. On its own, it’s harmless. It just fetches a file or a web page. But when you see it piped into bash, it becomes something different:

curl https://example.com/script.sh | bash

This downloads a script from the internet and runs it immediately. The | sends whatever curl fetches straight into bash, which executes it as commands on your computer. Uncommon, but when you see it, understand exactly what you’re downloading before approving.

Pro tip: If you’re not sure what a script contains or whether it’s safe, ask Claude to review it first. Deny the curl | bash command and say something like: “What is this script you are trying to run in bash? Before we run this, can you download the contents and evaluate if it’s safe or not? Help me understand what it does.” Claude can fetch the file, display its contents, and walk you through what each part does so you can make an informed decision.

When a Command Fails

Claude Code commands fail regularly. That’s normal. Here’s what the common errors mean:

• command not found — the tool isn’t installed. Claude Code will usually try to install it, or tell you what you need.
• No such file or directory — the path is wrong. Something about the file name or location doesn’t match.
• Permission denied — you don’t have access to that file or directory.

When something fails, Claude Code will diagnose it and try a different approach. If it gets stuck, copy the error message and paste it back. Errors in the terminal are almost always actionable once you know what they’re saying.

Getting Help with Commands

You don’t need to memorize what every command does. There are two quick ways to get answers.

Ask the command itself. Most terminal commands have a built-in help option. Add --help after the command name:

grep --help
git --help
npm --help

This prints a summary of what the command does and what flags it accepts. The output can be dense, but scanning it for the flag you’re curious about usually answers your question.

Ask Claude. If a command Claude Code wants to run looks unfamiliar, deny it and ask Claude to explain. Something as simple as “What does this command do?” will get you a plain-language breakdown. Claude can explain the command, each flag, and what will happen when it runs. This is one of the most practical ways to learn the terminal while using Claude Code.

You’re Supervising, Not Executing

You don’t need to be a terminal expert to use Claude Code. Your job is to understand enough to supervise what it’s doing.

Supervisors know enough to recognize when something looks right and when something needs a question. That’s the skill worth developing here.

Most of what Claude Code runs is safe. The unsafe things are usually obvious once you know what rm -rf means and when sudo is suspicious. You now know both.

Cheat Sheet & Glossary

I put together a 2-page reference card with every command and term from this post, including safety ratings for each one. Keep it next to your keyboard while you work, or print it out.

Get the free Terminal Cheat Sheet (PDF) →

If you’re new to the terminal and want to use Claude Code confidently, I offer coaching to help you get there. From project setup to understanding what’s happening under the hood, we can work through it together. Book a Claude Code Basics session.