Understand a terminal command.
Look up the tools, read the flags, and see what deserves a closer look.
Read before you run.
Enter a command to find familiar tools and questions worth asking.
This is a reading aid, not a shell parser or safety verdict.
New to the terminal? Start hereText with a structure.
Learn to read a commandA command can look like a flat line of text. The shell reads syntax; each program gives its arguments meaning.
grep -n "error" app.log | head -n 5The labels below are reading aids. The colours are optional, not part of the command.
grepCommand nameThe shell resolves the command. Aliases, functions and PATH can affect what runs.
-nOptiongrep interprets this argument: include matching line numbers.
"error"Quoted patternThe shell handles the quotes. grep receives
erroras an argument, without the quote delimiters.app.logFile argumentgrep treats this argument as the file to search. A relative path depends on the working directory.
|Shell operatorThe shell connects grep’s standard output to head’s standard input. The pipe is not an argument passed to grep.
head -n 5Next commandhead reads that input. Its
-n 5arguments request the first five lines.
Shell syntax → program arguments → output
Here the shell handles quoting and the pipe. grep and head interpret their own options and operands. Other syntax can trigger expansions, redirection or additional commands before a program sees its arguments.
The terminal app displays the session. The shell interprets the command language. Syntax highlighting depends on the shell and its configuration, not simply on whether you use Terminal, Ghostty or another terminal app. CMD and PowerShell have their own rules; this is not a Windows syntax reference.
Illustrative only. Logs can contain secrets, and the whole command and environment matter. The lookup helper above is not a shell parser or a safety verdict.
Command reference
Browse the reference18 commands found
pwdFind your bearingsPrint the current working directory. Relative paths in later commands start here.
What to check
The path can reveal a username or private project name. Shell built-ins and external versions can differ.
lsSee what is hereList files and directories. The -a flag includes hidden entries; -l adds details.
What to check
Filenames and permissions may be private. Output formatting is not a reliable interface for scripts.
cdMove through foldersChange the working directory of the current shell. cd .. moves to the parent directory.
What to check
A failed cd does not stop a later command separated by a semicolon. The working directory determines relative targets.
catRead a small fileWrite file contents to standard output. Multiple filenames are read in order.
What to check
Contents may include secrets. A large or binary file can overwhelm a terminal. Redirection around cat can still overwrite files.
headPeek at the beginningPrint the first lines of a file. -n 20 asks for twenty lines.
What to check
A preview can still expose secrets. It does not prove the remainder of a file is harmless.
tailWatch the endPrint the last lines. -f keeps watching as a file grows.
What to check
Logs may contain personal data or tokens. Following a file keeps a process running until interrupted.
grepFind matching linesSearch text for a pattern and print matching lines. -n includes line numbers.
What to check
Patterns have their own syntax. A nonzero exit status can mean no matches, not a broken command. Recursive searches may expose private content.
findLocate files preciselyWalk a directory tree and select entries using tests such as -name.
What to check
find can also execute commands with -exec or delete files with -delete. Order and quoting matter.
mkdirMake a new directoryCreate a directory. -p creates missing parent directories as needed.
What to check
Creates filesystem entries and may fail because of permissions or existing files. -p does not prove the chosen location is correct.
cpCopy with careCopy a file to a destination. Recursive options copy directory trees.
What to check
An existing destination may be overwritten. Symlinks, permissions and recursive behavior vary by options and platform.
mvMove or renameMove a file or rename it within a directory.
What to check
An existing destination can be replaced. Moving across filesystems may involve copying and removing the original.
rmRemove filesRemove named filesystem entries. -r descends into directories; -f suppresses some prompts and errors.
What to check
Usually bypasses the desktop Trash. Wildcards and unexpected variables can greatly expand the target; -rf is not a safety check.
chmodChange permissionsChange who can read, write or execute a file.
What to check
Executable permission does not make a script trustworthy. Broad or recursive permissions can expose sensitive data or weaken security.
sudoUse elevated authorityRun a permitted command as another user, commonly root, according to local policy.
What to check
Greater privileges amplify mistakes. It is not a fix for an unexplained permission error, and local policy can vary.
gitUnderstand repository changesTrack and inspect versioned work. git status summarizes the working tree and staging area.
What to check
status is observational, but reset --hard, clean and restore can discard work; push sends data to a remote. A repository may contain configured hooks and helpers.
curlTalk to a URLTransfer data to or from a server. -I asks for response headers instead of the response body.
What to check
Requests disclose network information to the destination. Flags can upload files, include credentials or write output locally. Piping a download into a shell executes remote code.
npmManage JavaScript packagesInstall dependencies and run scripts defined by a JavaScript project.
What to check
Installations can run package lifecycle scripts and change package or lock files. A familiar package name does not verify its publisher or contents.
sshConnect to another machineOpen an encrypted connection to a remote host, often for an interactive shell.
What to check
Commands run on the remote machine. Host-key warnings matter; forwarding and authentication options change access and exposure.
Risk depends on the whole command and your environment, not just the command name.
Shell operators
How they fit together|Pass output along&&Continue on success||Continue on failure;Run the next command>Replace an output file>>Append to an output file2>Redirect errors$()Substitute command output*Expand a pattern
Learn the basics
All guides- Read a command before you run itA calm, repeatable way to turn a wall of terminal text into a decision.Start here · 5 min
- Pipes are plumbing, not magicFollow data through pipes, files, and error streams without losing the plot.Build confidence · 6 min
- “Safe” depends on the situationLearn the questions that matter more than a green badge.Start here · 4 min
- A better conversation with your agentKeep the speed of an agent without giving up understanding or control.Build confidence · 5 min
- Small syntax, big consequencesUnderstand quoting, exit codes, expansion and the edges of simple explanations.Go deeper · 8 min