Day zero
Getting started: open the terminal and find your feet.
Never used a command line? Start here. In fifteen minutes you'll know what a terminal is, how to read the prompt, what a command and a file path are, and how to move around — enough that every other page in this guide makes sense.
pwd where am I?ls / ll what's here?cd name go into a foldercd .. go up oneclear also clears itcmd --help how do I use this?#What the terminal is
A terminal is a window where you type commands instead of clicking buttons. You type a command, press Enter, and the computer does the thing and prints the result. That's the whole loop. It feels old-fashioned for about a day, and then it feels like a superpower — because typing a precise instruction is faster and more repeatable than hunting through menus.
On this Mac the terminal app is Ghostty. Open it the way you open anything: press ⌘Space (or your Raycast hotkey), type ghostty, and hit Enter. You can keep it in the Dock once it's open. Everything else in this guide — the shell, tmux, Neovim — runs inside this window.
A fresh Ghostty window opens in your home folder, shown as ~. That is the neutral starting place; from there, use z, cd, or tmux's session switcher to jump into a project.
Two words for two things. Ghostty is the window. The shell (here, zsh) is the program running inside it that actually reads your commands. You'll hear "the terminal" used loosely for both — that's fine for now.
AI coding agents work by reading files, running commands, editing code, and showing diffs. Learning the terminal is how you understand what the agent is doing and step in confidently when it needs direction.
#Reading the prompt
When the shell is ready for a command, it shows a prompt and waits. On this setup the prompt is drawn by starship and shows your operating system and the folder you're in on every line, followed by how long the last command took and a ❯ where your typing goes. The folder appears on every line on purpose: when you copy terminal text into an AI tool, the agent can see exactly which project and folder your commands ran in — context it would otherwise have to ask for. Inside a project the path starts at the project's folder (…/groundwork rather than the full path from home), so the project name stays visible no matter how deep you go:
# OS project cursor sits here
…/groundwork ❯ _Throughout this guide you'll see commands written with a $ in front, like $ ls. The $ just stands for the prompt — don't type it. Type the part after it. (The copy button on each code block strips it for you.)
#A command has a shape
Almost every command is the same three parts: the command, some optional options (also called flags), and the thing you're acting on.
$ ls -l ~/code
# │ │ └─ argument: what to act on (a folder)
# │ └─ option/flag: changes how it behaves (-l = long list)
# └─ command: the program to runOptions usually start with a dash. Short ones are a single letter (-l); long ones are spelled out (--all). When you don't know what a command can do, ask it:
$ ls --help # a quick summary of options
$ man ls # the full manual — press q to quit#Files, folders, and the path
Your files live in a tree of folders (also called directories). A path is the address of a file or folder in that tree, with slashes between each step: /Users/you/code/groundwork. A few symbols are worth knowing because they appear everywhere:
/ | The very top of the tree (the "root"). Also the separator between folder names. |
~ | Your home folder — shorthand for /Users/yourname. Most of your stuff lives under here. |
. | "Here" — the folder you're currently in. |
.. | "Up one" — the folder that contains the current one. |
A path that starts at the top (/Users/you/code) is absolute — it means the same thing from anywhere. One that starts from where you are (code/groundwork or ../notes) is relative. Both are normal; you'll use whichever is shorter.
Files and folders whose names start with a dot — .zshrc, .config, .git — are "hidden" and don't show by default. They're where configuration lives (that's what "dotfiles" means). See them with ls -a or ll.
#Moving around
Four commands cover ninety percent of getting around. Try each as you read it.
pwd | Print working directory — shows the full path of where you are right now |
ls · ll | List what's in the current folder. ll is the detailed version (sizes, dates, Git status) |
cd folder | Change directory — step into a folder. cd ~ goes home, cd .. goes up, cd - jumps back to where you just were |
z name | Jump to a folder you've visited before from anywhere, by a few letters of its name (this setup's zoxide) |
$ pwd # /Users/you
$ cd code # step into ~/code
$ ll # see what projects are here
$ cd groundwork # into one of them
$ cd .. # back up to ~/codePress Tab while typing a file or folder name and the shell completes it — start cd mac, hit Tab, and it fills in groundwork/. Press ↑ to bring back a previous command instead of retyping it. These two habits save more keystrokes than anything else.
#The survival kit
The handful of keys that get you out of any situation. Memorize these five and you'll never feel stuck.
| CtrlC | Stop the current command. Something running too long, or you changed your mind? This cancels it and gives the prompt back |
clear or CtrlL | Wipe the screen clean (history's still there with ↑). Prefer clear — inside tmux, CtrlL jumps panes instead |
| ↑ / ↓ | Step back and forth through commands you've already run |
| q | Quit a full-screen viewer (a man page, a long git log) and return to the prompt |
exit | Close the shell / terminal window |
You probably pressed CtrlS, which freezes the screen. Press CtrlQ to unfreeze. And if a command seems hung, CtrlC almost always rescues you.
#You really can't break it
Two reasons to experiment freely. First, the commands on this page only look at things — pwd, ls, cd change nothing. Second, this whole machine is rebuildable: every config came from the setup repo, so if something ever gets weird, one chezmoi apply puts it back. The only commands that can destroy work say rm (remove), --force, or --hard — and the Git page teaches you to pause on those. Everything else is safe to poke at.
#Practice
Open it and look around
Launch Ghostty. Run pwd to see where you are, then ll to list what's there. You're standing in your home folder — these are your files.
Walk the tree
Use cd to step into a folder, ll to look, and cd .. to back out. Try Tab halfway through a folder name to autocomplete it. Lost? cd ~ always brings you home.
Ask a command for help
Run ls --help and skim it. Then man ls for the full manual — scroll with j/k or arrows, and press q to leave. Getting comfortable quitting man is half the battle.
Recall and cancel
Run something slow like ping example.com, watch a few lines, then stop it with CtrlC. Press ↑ to bring the command back without retyping. Finish with CtrlL to clear the screen.
That's the floor — you can now follow any page here. Natural next steps: the Setup & chezmoi page (how this machine builds itself), Customizing (how to keep personal tweaks), then Shell & CLI (the faster tools and line-editing tricks), and tmux (many panes in one window).
#Going deeper
- The Missing Semester: the shell — MIT's free, beginner-friendly first lesson.
- Command line & Unix — the next page here: core commands, scripting, and what Unix actually is.
- The Linux Command Line — the best free book for newcomers (the basics apply on a Mac too).
- Ghostty docs — the terminal app itself.