Moving Around: Your Mental Map of the Machine

A fresh terminal window is quiet: a prompt, a blinking cursor, and no other clues. But you're not floating in a void — the shell has already placed you inside a folder, called your working directory. Two commands turn the void into a map.

pwd ("print working directory") answers the question in one line:

pwd
# /home/vibe

That answer — /home/vibe — is a path, the full address of the folder you're standing in (paths get their own section next). It also names your home directory — the folder that belongs to your account, where your files, settings and downloads live. Every account on the machine gets one, and this one is the home of the account named vibe — you. Now look around with ls ("list"):

ls
# documents  notes.txt  projects

The Hidden Layer: Dotfiles

Plain ls is holding out on you. Any file or folder whose name starts with a dot — a dotfile — is hidden by default. That's where configuration lives: .bashrc, your shell's own settings file (Your Shell Config); .gitignore; and the .env file holding your API keys — an API being a door a service opens for other programs rather than for people, which is why that file is worth hiding (curl — Ask the Network). Add -a ("all") to see them:

ls -a
# .  ..  .bashrc  .config  documents  notes.txt  projects

A First Peek at ls -l

The long listing packs a lot into each line. For now, read just three things: the leading d means "directory," the number before the date is the size in bytes, and the name is at the end. A byte is one character's worth of storage, so a 118-byte file holds roughly 118 characters. The rest of that cryptic string is the permissions code, and we decode it fully in Permissions & Config.

ls -l
# total 12
# drwxr-xr-x  3 vibe staff 4096 Jul 10 09:14 documents
# -rw-r--r--  1 vibe staff  118 Jul 12 08:30 notes.txt
# drwxr-xr-x  4 vibe staff 4096 Jul 11 17:02 projects

Three things in that block mislead on sight. total 12 is not a count of the files — it's how much disk they take up, measured in blocks rather than bytes. The small number just after the permissions is a link count, not a second size. And the two names beside it, vibe staff, are the file's owner and its group. All three get taken apart in Reading ls -l.

Every file on your machine has an address, and that address is called a path. Learn to read paths and the whole filesystem snaps into focus — it's one big upside-down tree, and you can point at any leaf from anywhere.

Everything starts at the root, written as a single slash / — the one folder every other folder lives inside. Everything else hangs somewhere beneath it, and a path is the walk from one point to another, with / between each step. Fair warning, because the word gets reused: this root is a place. The other root you'll meet is a person, the administrator account in sudo, and the two have nothing to do with each other.

Reading the tree: the file .env lives at /home/vibe/projects/app/.env — root, then home, then vibe, then projects, then app.

The branches sitting beside home at the top belong to the machine rather than to you, and a handful come up often enough to name. /bin and /usr/bin hold binaries — the programs themselves. /etc holds system-wide configuration — that's what /etc/hosts in the table below is, the short list of names your machine resolves itself before asking the network. /tmp is scratch space anyone can write to and the machine may clear without asking. And /usr, despite the spelling, is where the system's own software lives — it has nothing to do with users.

Absolute vs. Relative

An absolute path starts at the root with / and works from anywhere — a full street address. A relative path starts from wherever you're currently standing — "two doors down." Both name the same file:

# Absolute: works no matter where you are
cat /home/vibe/projects/app/README.md

# Relative: works if you're standing in /home/vibe
cat projects/app/README.md

The Four Shortcuts Every Path Uses

And they compose. Standing in ~/projects/app, the path ../../documents means "up two levels, then into documents." Now you can re-read the AI's instruction: ~/projects/app/.env is a hidden file named .env, inside app, inside projects, inside your home directory.

Those quotes are worth understanding properly, because you'll be reaching for them for the rest of the course. There are two kinds, and one difference that matters. Single quotes are literal — nothing inside them means anything to the shell, so '$HOME' stays five characters instead of turning into the path to your home directory, and '*.txt' stays five characters instead of becoming a list of files. Double quotes still let $NAME and $(...) expand into their values (Environment Variables) while still protecting the spaces. Reach for single quotes when you want the shell to keep its hands off, double quotes when you want a value in the middle of a phrase.

A backslash does the same job for exactly one character: My\ Projects is one filename, not two words — which is what TAB completion is doing when it "escapes" a space for you. Anything the shell would otherwise read as punctuation — a space, a *, a $, a quote mark — can be defused by putting a backslash in front of it.

Try It: Mind the Gap

You can read the map; now walk it. cd ("change directory") moves you to any path you can name — and since you just learned to name every path on the machine, you can now go anywhere.

cd projects/app   # Walk down into a folder (relative path)
pwd               # /home/vibe/projects/app — always verify
cd ..             # Up one level, to projects
cd ~              # Jump home from anywhere (plain 'cd' does the same)
cd -              # Bounce back to wherever you just were

That last one is a gem most tutorials skip: cd - toggles between your two most recent locations — perfect when you're hopping between a project and a config folder. It's also one of the rare places a lone dash is a value rather than a flag (Getting Help) — here it stands in for "the last place I was," not for a setting. And remember the habit from 2.2: type cd, a few letters, then TAB your way down the tree.

Try It: Find the Lost API Key

So far you've been a tourist — looking, never touching. Time to build. Two commands create the skeleton of every project you'll ever start: mkdir for folders and touch for empty files.

mkdir notes            # One new folder in the current directory
mkdir src tests docs   # Three at once — src is short for "source"
touch README.md        # One new, empty file
ls                     # Verify — trust, but verify

Plain mkdir has one rule: the parent must already exist. Ask it for a nested path and it refuses:

mkdir src/components/buttons
# mkdir: cannot create directory 'src/components/buttons': No such file or directory

mkdir -p src/components/buttons   # -p = parents: create every missing one on the way
# (no output — in the shell, silence means success)

touch has a funny origin story: its real job is updating a file's "last modified" timestamp — touching it. But if the file doesn't exist, touch creates it, empty. That side effect became its main job: it's the standard way to say "make me a blank file right here."

mkdir -p my-app/src/components my-app/tests
touch my-app/README.md my-app/src/main.js
ls -R my-app   # -R walks into every folder inside, and those folders' folders too

Nothing on the machine requires that shape — src, tests and docs are a convention other people will recognize, not a rule anything enforces. And that walking-into-everything behaviour has a name, recursive, which comes back in Copying as the flag that lets copying and deleting reach a whole tree at once.

An AI agent just wrote a config file into your project. Before you trust it, you want to read it — without the ceremony of opening an editor. The terminal has a whole toolkit for exactly this, graded by file size.

cat config.yaml
# port: 8080
# debug: false
# database: ./data/app.db

That file is YAML — a config format built to be read by humans, one key: value to a line. (A config file being any file that changes how a program behaves without changing the program itself.)

A few other extensions keep turning up and work the same way. .csv is comma-separated values: one record per line, the fields split on commas, the first line usually naming the columns. .md is Markdown — plain text with light formatting marks, like # for a heading. .sh is a shell script. Every one of them is ordinary text underneath: a file of characters, each character stored as a number. That's why the commands below read all of them equally well, and why an extension is a convention for humans and editors rather than the thing that makes a file work.

cat (short for "concatenate") is perfect for short files — it prints everything and returns your prompt. But cat a 10,000-line log and it firehoses past you. For anything long, you want a pager:

less server.log
# Opens a full-screen reader:
#   space / b     page down / up
#   arrow keys    scroll line by line
#   /error        search for "error" — press Enter to run it (n = next match)
#   q             QUIT — back to your prompt

While we're here, four escape hatches worth memorizing now — because each one has stranded somebody for an embarrassingly long time. Two are characters you type; two are chords, held down together in one motion. The comments say which is which:

q            # type it — any pager: less, or a man page. One keypress, no Enter
:q!          # type it — vim. Press Esc FIRST, then these three, then Enter (:wq saves instead)
Ctrl+X       # chord — nano. It says so at the bottom, but nobody reads it
Ctrl+C       # chord — a running command, or a line you typed but haven't run

:q! is the famous one. Git — the tool that records snapshots of a project as you work (Your Shell Config) — drops you into vim on most machines to write the note that goes with a snapshot. The keyboard stops behaving, there's no visible way out, and the answer is Esc then :q! then Enter, which leaves without saving. You are not expected to learn vim today; you're just expected to be able to leave.

Sometimes you only care about the edges of a file — the header row of a CSV, or the most recent lines of a log. That's head and tail:

head server.log        # First 10 lines
head -n 3 server.log   # First 3 lines
tail server.log        # Last 10 lines — where the newest log entries live
tail -n 20 server.log  # Last 20

Try It: Build Your Workspace