5. Reading the manual: man, --help, and tldr

Description

By the end of this lesson you will be able to figure out on your own how any command on your system works — one this guide never mentioned — without leaving the terminal: open its full manual, ask it for a quick summary of its options, find real usage examples, and even discover the name of a command you do not know yet based on what you want to accomplish.

This matters because sooner or later you are going to be connected over SSH to a server with no browser, or a coworker is going to hand you a command with an option you have never seen, and the only source of truth available right there, without leaving that terminal, is the documentation already installed on that machine. Knowing how to read it is the difference between getting stuck and solving it on your own.

Connection to the module: the previous lesson taught you the anatomy of a command — what an option is, what an argument is, how they combine. This lesson gives you the official source for that anatomy for any new command. The next one changes topic entirely: it leaves individual commands behind and starts this guide's central mental model, the filesystem as a tree.

The manual as the source of truth: man

Think about a technician repairing an engine model they have never seen before. They do not guess by trial and error, and they do not trust a three-year-old YouTube video about "a similar engine": they look up the manufacturer's manual for that exact model. man is exactly that for a command: the manual that the same package that installed the command also installed, for the exact version running on your machine — not a blog post that might describe a different version, and not what a language model "remembers" having seen during its training, which can be outdated or simply wrong for your system.

Technically, man (from manual) opens a command's documentation page inside a text pager — almost always less — so you can scroll, search, and quit without the content spilling off your screen. Manual pages are organized into numbered sections, and the ones you will run into most often are:

This is not trivia: some names exist in more than one section with completely different content. The classic case is passwd: man passwd opens section 1, the command you use to change your password. But passwd(5) also exists, section 5, which describes the format of the /etc/passwd file — not how to change your password, but how that file is structured line by line. To ask for a specific section, the number goes before the name:

man 5 passwd

Without the number, man gives you the first section where it finds the name — almost always 1 — which is not always the one you are looking for.

Worked example

Open the manual for a command you already know from the previous lesson:

man ls

This replaces your terminal with the pager, showing something like this in the first lines:

LS(1)                            User Commands                           LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List information about the FILEs (the current directory by default).
       Sort entries alphabetically if none of -cftuvSUX nor --sort is
       specified.

What to expect: NAME gives you, in one line, what the command does — it is the same thing whatis ls returns. SYNOPSIS is the part most worth learning to read, because it summarizes the entire way of using the command in a compact notation that is standard across nearly every manual page you will ever open:

• Text in bold or written as-is (ls, [OPTION], [FILE]): type it exactly like that.
• Text in italics or UPPERCASE (OPTION, FILE): it is a placeholder — replace it with your own value. Many pages use uppercase instead of real italics, because italics do not always stand out well in a plain-text pager with no colors.
• Square brackets [ ]: what is inside is optional. ls works with no options and no files.
• Ellipsis ...: what precedes it can repeat. [FILE]... means "zero, one, or several files," not just one.
• Vertical bar |: separates mutually exclusive alternatives — pick one, not both.

With those five rules, ls [OPTION]... [FILE]... reads like this: "ls, followed by zero or more options, followed by zero or more files or folders." None of that is required, and that is why plain ls — with nothing after it — is also valid: it uses the current directory by default, exactly as DESCRIPTION says.

If you are on macOS, your ls is the BSD version, not the GNU one shown above: the synopsis groups all the short options inside a single bracket and does not accept long options (--something). The listing style changes between implementations, but the notation — brackets, ellipsis, uppercase — is the same in any manual page you open, on any system.

To move around inside the page, you are already using less even if you did not ask for it:

• Space or f advances one screen, b goes back one.
• /pattern searches forward for that text; Enter confirms the search, n jumps to the next match, N (uppercase) to the previous one.
• g goes to the beginning of the document, G (uppercase) to the end.
• q closes the manual and hands you back the terminal.

Try searching for the option that sorts by size: inside man ls, type /-S and press Enter. less jumps straight to the line documenting -S, instead of you having to search by reading top to bottom.

--help: the quick answer once you already know the command

man is exhaustive, but opening a full pager to remember a single flag is more work than needed. Most commands — especially GNU ones, common on Linux and in WSL — accept --help: they print a usage summary directly to the terminal, no pager, and you can combine it with what you already know from the previous lesson about basic pipes:

ls --help

What to expect (a representative slice; the real option list is longer):

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
  -S                         sort by file size, largest first
  ...

--help does not replace man: it is a usage note written by the program itself, while the manual page is documentation maintained separately, more complete, with examples and warnings that rarely fit on a single summary screen. If you only need to remember a flag's exact name, --help is faster; if you need to understand a nuanced behavior, man is still the reference.

A platform detail that connects with lesson 3: if you are on macOS, many system commands come from BSD, not GNU, and BSD did not universally adopt the --help convention. It is common for ls --help on macOS to fail with an unrecognized-option error instead of showing you anything useful. That is exactly where man ls — which does exist on any Unix system — becomes indispensable instead of optional.

tldr: real examples as a complement, not a replacement

A full manual documents every flag with precision, but it does not always tell you which combination people actually use in practice for the everyday task. That is where tldr (too long; didn't read) comes in: a community project (tldr-pages) that maintains short pages with real usage examples for thousands of commands, meant to complement the manual — not replace it.

tldr does not come preinstalled; you need a client. There are several, and any of them will do — install whichever your package manager makes easiest:

# Python client, works on any system with pipx
pipx install tldr

# Rust client (tlrc), via Homebrew on macOS/Linux
brew install tlrc

With the client installed, ask for a command's examples:

tldr tar

What to expect (the exact content varies between page versions, but the shape is always this):

tar

  Archiving utility, often combined with a compression method.

  Create an archive from files:
      tar cf {{target.tar}} {{file1 file2 ...}}

  Create a gzipped archive:
      tar czf {{target.tar.gz}} {{file1 file2 ...}}

  Extract a (compressed) archive into the current directory:
      tar xvf {{source.tar[.gz]}}

  List the contents of a tar file:
      tar tvf {{source.tar}}

Compare this to opening man tar: the manual documents dozens of flags with formal precision, but it does not tell you which combination solves "I want to decompress this right now." tldr does. What tldr does not have is the manual's full coverage or authority: these are pages maintained by volunteers, they can fall behind a new version of the command, and they almost never explain edge cases. Use it to quickly recall the common shape; go back to man when you need certainty about exactly what each option does before running something you cannot undo.

apropos: finding a command when you do not know its name

Everything above assumes you already know the command's name. apropos solves the problem that comes before that one: searching by keyword through the short description of every manual page installed on your system, to find the name you do not know.

apropos "list directory"

What to expect (something like this, exact wording depends on your system):

ls (1)               - list directory contents
dir (1)               - list directory contents
vdir (1)              - list directory contents

man -k word does exactly the same thing as apropos word — they are the same mechanism with two names. If instead you already know the exact name and just want its one-line description, whatis name is the version with no fuzzy search: it matches the full name, not loose words inside the description.

apropos searches an indexed database, not the manual files directly, and that database is built by the mandb program. If your system is new or you just installed packages, that database might not exist yet or might be out of date — which produces the message nothing appropriate even for a keyword that should have results. Rebuilding it is a single line:

sudo mandb

Asking a language model for a command: legitimate, but verify before running it

Asking an AI assistant "how do I delete all .tmp files in this folder and its subfolders?" is legitimate and, most of the time, faster than searching a manual from scratch. That is not the problem. The problem is running the answer without having understood every part of it.

A language model can get the command right, and it can also miss a subtlety — an option for a different version of the command, a flag that does something slightly different from what you think, a path interpreted differently than you expected. The rule that will serve you for your entire career with the terminal is simple: a command you do not understand does not get run. You read it first in its manual — with man, with --help, or at least by asking the same model what each part does — and only then run it. This is non-negotiable when the command includes rm (deletes, and in most cases with no recycle bin), sudo (runs it with administrator privileges, over your entire system), or a redirection > (overwrites an entire file with no prompt, something you will see in detail in module 3). The terminal does not have an "are you sure?" checkbox for most of these cases: the confirmation has to happen in your head before pressing Enter, not after.

Common mistakes

1. Assuming man and --help always show the same thing (conceptual). They are two different sources written for different purposes: --help is a summary generated by the program itself, while the manual page is separate documentation, maintained by whoever packages the operating system or the project, almost always more complete. There is also an asymmetry that surprises people: the shell's built-in commands (cd, export, alias, history) do not have their own independent manual page, because they are not separate programs — they live inside bash or zsh. How to spot it: man cd returns "No manual entry for cd" or opens your shell's general page (man bash) instead of a dedicated one. How to fix it: for shell built-ins, use help cd (in bash) or search inside man bash/man zshbuiltins instead of expecting a page of its own.

2. apropos answers "nothing appropriate" and you conclude the command does not exist (practical). The message does not mean "this does not exist on your system": it means the database apropos queries — built by mandb — was never generated, or fell out of date after installing new packages. How to spot it: you search for a word you know for certain should have results (for example apropos copy, which should find cp) and nothing shows up. How to fix it: sudo mandb rebuilds the index; try the search again afterward.

3. Literally copying a tldr example (or one from a language model) without adapting it to your case (conceptual). tldr examples are generic by design — they use placeholders like {{target.tar}} — and a language model answers your question, it does not know the exact state of your system. If the example includes rm, sudo, or > and you paste it without checking what path or file you are putting in place of the placeholder, the risk is not that the command is "wrong": it is that it is right for a generic case and wrong for yours. How to spot it: ask yourself "could I explain out loud what each word of this command does?" and you cannot. How to fix it: replace each placeholder deliberately and, if the command touches something irreversible, first run a version that only lists or only prints, before the version that acts.

Exercises

1. Reading a synopsis. Run man mkdir and look at its SYNOPSIS line. Without running anything yet: is the directory argument required or optional according to the notation? Can you pass more than one directory in a single call? Justify your answer by pointing to which notation symbol tells you so.

2. Telling manual sections apart. Run apropos passwd (or man -k passwd, it is the same thing). You will see at least two entries with the same name passwd but a different section number in parentheses. Which command specifically opens the one describing the file format, and not the command for changing your password?

man 5 passwd

3. Finding a flag with --help and a pipe. Without opening the full manual, use ls --help combined with grep (you saw it in passing in the previous lesson as part of terminal ergonomics; it gets covered in depth in module 3) to find, in a single line of output, which short flag sorts by file size from largest to smallest.

ls --help | grep -i size

4. Diagnosing a broken apropos. A coworker swears cp does not exist on their system because apropos copy returns nothing. You know cp is in fact installed — they used it five minutes ago. What is most likely going on, and what command fixes it?

sudo mandb

Summary and next step

You can now open the full manual for any command with man, read its synopsis to know what is required, what is optional, and what repeats, ask for a quick summary with --help, find real usage examples with tldr, search for a command by what it does with apropos when you cannot remember its name, and verify — before running — any command someone else or a language model suggested to you.

Before moving on you should be able to:

• Open man for a command you have never used and say, just by reading the synopsis, which of its arguments are required.
• Explain the difference between what man, --help, and tldr offer, and when you would use each.
• Rebuild apropos's database when it responds "nothing appropriate" for no apparent reason.

With this, you no longer depend on this guide — or on any tutorial — to learn a new command: you know where the official source is and how to read it. What you are still missing is the full map of the terrain where all those commands run: the next lesson installs this guide's central mental model, the filesystem as a single tree rooted at /, and the difference between moving around it via absolute and relative paths.

Resources

• man-pages(7) — Linux manual page — the official source for the synopsis notation conventions (bold, italics, brackets, ellipsis, vertical bar) used in this lesson.
• apropos(1) — Linux manual page — official reference for apropos, including its relationship to the database mandb builds.
• whatis(1) — Linux manual page — apropos's sibling tool: a one-line description from a command's exact name.
• tldr-pages — official repository — the community project behind tldr, with the up-to-date list of clients available to install.
• GNU Coreutils Manual — Invoking ls — official documentation for the ls options used in this lesson's examples.