First Contact

The terminal has a fearsome reputation, so let's start by deflating it: it's just an app. It sits next to your browser and your music player, it opens like them, and it closes like them. Here's where to find yours.

macOS

Press ⌘ Space — hold Command and tap Space — to open Spotlight, the macOS search bar. Type Terminal, press Enter. That's it. (The long way: Applications → Utilities → Terminal.app.) The stock app is a genuinely good place to start — since macOS 26 "Tahoe" it has true color and modern themes, so there's nothing to install today. Pin it to your Dock while it's running (right-click its icon → Options → Keep in Dock) — you'll be back.

Linux

Press Ctrl+Alt+T on most desktops, or find Terminal / Console in your application menu.

Windows

Open Windows Terminal from the Start menu — it's been the default console since Windows 11 22H2, so it's already there — then pick your Ubuntu (WSL) profile from the dropdown next to the new-tab button. If you chose Git Bash instead, open Git Bash from the Start menu. Either way, make sure you're in a bash window — not PowerShell — before following along (the intro explains the difference).

Whatever you opened, you should now be looking at a mostly-empty window with a prompt and a blinking cursor — the shell, waiting for your first words.

A command is a word — sometimes followed by more words — typed at the prompt. Nothing happens while you type. Nothing happens while you hesitate. The shell only acts when you press Enter. Let's have your first conversation.

Start with a question the machine can't get wrong — who are you? In every code block from here on, the first line is what you type and the # lines are the machine's reply (Introduction has the full legend).

whoami
# vibe

The shell answered with your username. Now make it say something — echo repeats whatever you give it, and the quotes hold the two words together as one message instead of two separate ones (Paths has the rule):

echo "Hello, terminal"
# Hello, terminal

Ask for the time, and then wipe the slate clean:

date
# Sat Jul 12 10:15:42 PDT 2026

clear
# The screen empties - the text is still there, just scrolled out of sight

The screen went blank but nothing was deleted: that's the terminal's scrollback, and scrolling up brings every answer back. The shell also keeps its own record of the commands you typed (History Superpowers) — a separate list, and clear leaves that alone too.

Now the important experiment: type something wrong on purpose. Misspell a command and press Enter:

ecoh "hello"
# bash: ecoh: command not found

Read that reply back like a sentence in three parts: bash is who's complaining — the shell, not your command — ecoh is the word it choked on, and command not found is the complaint. Every error you meet from here on has that shape; only the complainer changes.

Try It: Say Hello to the Machine

You will never memorize every command — nobody does. What experienced people memorize instead is how to look things up. The terminal ships with its own documentation, and it's always three keystrokes away.

Two ways in, and you'll use both. --help prints a compact summary of what a command does and which flags it accepts, straight to your terminal. man opens the full manual. Which one answers you depends a little on your machine — we'll get to that — but between them, nothing stays a mystery for long.

Flags first, because that summary is mostly a list of them. A command line is a sentence. The first word is the program. Everything after it is either a flag — a request to behave differently — or an argument, the thing to act on. The shell tells them apart by one character: a leading dash. ls -a means "run ls, and switch on the a behaviour". ls a means "run ls on something called a", which is a different question entirely and usually an error. That dash is doing real work; it is not decoration.

The shell chops your line at the spaces and hands over the pieces one at a time, which is why a filename with a space in it needs quoting. Four rules cover almost everything else you'll meet:

• One dash, one letter. -a, -l. Short, fast, and what you type day to day.
• Two dashes, a whole word. --all, --help, --version. Longer to type, far easier to read six months later in a script.
• A comma joins two spellings of the same flag. When help output or a manual page prints -a, --all, that is one flag with two names. Use either. Never both.
• Single letters cluster. ls -la is ls -a -l written faster; add a t — ls -lat — and you've asked for them sorted newest first as well. Only single letters cluster this way; --all --long doesn't squash into anything.

ls --help
# Usage: ls [OPTION]... [FILE]...
# List information about the FILEs (the current directory by default).
#   -a, --all        do not ignore entries starting with .
#   -l               use a long listing format
# ...

That Usage: line has a shorthand of its own: square brackets mean optional, ALL-CAPS words are placeholders you swap for your own, and a trailing ... means "as many of these as you like". OPTION is the older word for a flag and you'll see both, often on the same page. So ls [OPTION]... [FILE]... reads: any number of flags, then any number of files, none of it required. Nothing in brackets is ever typed literally.

On a Mac, that same command is an error — and that's fine

Mac and Linux carry two different lineages of the same veteran tools. macOS ships BSD's versions; Linux — and WSL and Git Bash with it — ships GNU's. GNU tools nearly all answer to --help. Most of the BSD ones have never heard of it, and say so:

ls --help
# ls: unrecognized option `--help'
# usage: ls [-@ABCFGHILOPRSTUWXabcdefghiklmnopqrstuvwxy1%,] [--color=when] [file ...]

Same three parts as ecoh earlier, and the same reassurance: nothing broke, and you weren't punished for trying. Here the complainer is ls rather than the shell — it names the one thing it didn't understand, then prints its usage line anyway — so you still got the flag list, just terser and stripped of the descriptions. That's the shape of most terminal errors. Read the words; they usually say precisely what tripped them up.

ls, du, head, cut, wc, stat and date all behave this way on a Mac. So does grep, which quietly prints its usage line without even calling it an error. The tools you install yourself later — curl, git, tar, jq, brew — take --help everywhere, Macs included. For everything else on a Mac, the answer is the manual.

This course uses angle brackets for the same job — when you see man <command>, you type man ls, never the brackets. That matters more in a shell than elsewhere: < is a real operator in its own right, so typing the brackets produces an error that points nowhere near your mistake.

For the full story — and, on a Mac, for most of the built-in commands — there's man — the manual, installed with your system since before the web existed. It comes in numbered sections, because one name can mean two things: crontab is both a command you run and a file format that command reads, so man 1 crontab and man 5 crontab are two different pages. Section 1 is commands, section 5 is file formats. Leave the number off and you get the first match, which is nearly always the one you meant:

man ls
# Opens the complete manual page for ls

man -k download
# wget(1) - The non-interactive network downloader.
# ...

The second is for when you don't know the command's name yet. -k is for keyword: it searches every manual page's one-line description and prints each match with its section number in brackets. Your machine will list many more than this one.

Worth knowing where that search stops, though, because it will bite you. It reads only that one-line description, not the page. curl downloads files for a living, and man -k download does not find it — its description reads transfer a URL, and the word "download" appears nowhere in it. So a -k search that comes back thin means your keyword didn't match anyone's phrasing, not that no such command exists. Try a synonym before you conclude anything.

Man pages are thorough but dense. For a friendlier take, the community-written tldr pages — too long; didn't read — show each command as a handful of practical examples. tldr doesn't come with your system, though: it's a third-party command you install first (Package Managers). Nothing to install to read it, happily — the web version is at tldr.inbrowser.app, which is where the output below comes from.

tldr tar
# tar
#   Archiving utility.
#   - Create an archive from files:
#     tar cf target.tar file1 file2 file3
#   - Extract an archive to the current directory:
#     tar xf source.tar
# ...

Those cf and xf look like they've lost their dash, and they haven't: tar is old enough to accept its letters bare, so tar cf and tar -cf are the same command. It's one of the few commands in this course that gets away with it — assume the dash everywhere else.

A third way to get help

You have a third source of help the man-page authors never imagined: paste any command into your AI assistant and ask "what does this do, flag by flag?" It's the fastest explanation you'll get — and it works in reverse too, when the AI is the one proposing the command. The AI vendors know it: Anthropic's Claude Code docs now ship their own "never opened a terminal before" guide — if you use a coding agent, being able to read its commands is part of using it safely. But language models can be confidently wrong about flags, so close the loop:

Try It: Read the Manual First