tldr: The First Thing I Install on Every Machine

New server. Fresh container. Borrowed laptop. Whatever the situation, one of the first things I install is tldr.

Not vim. Not zsh. tldr.

The problem with man

man pages are reference manuals. They are comprehensive, precise, and completely unhelpful when you just need to know how to do the one thing you came for.

You run man tar. You get 3000 lines of every flag, every mode, every edge case going back to 1979. Somewhere in there is the answer to “how do I extract a .tar.gz.” Good luck finding it before your SSH session times out.

man is a reference. It’s not a guide. When you’re in the middle of something and need a quick answer, you don’t want the encyclopedia. You want the cheat sheet.

What tldr does

tldr gives you exactly what man doesn’t: short, practical examples with a one-line description for each.

terminalbash

tldr tar

tar

Archiving utility.
Often combined with a compression method, such as gzip or bzip2.

- Create an archive and write it to a file:
  tar cf target.tar file1 file2 file3

- Create a gzipped archive and write it to a file:
  tar czf target.tar.gz file1 file2 file3

- Extract a (compressed) archive into the current directory:
  tar xf source.tar[.gz|.bz2|.xz]

- Extract files matching a pattern:
  tar xf source.tar --wildcards "*.html"

That’s it. Four examples. Each one does something you actually need. No history lesson. No flag matrix. No scrolling.

Why it’s the first install

When I land on a new machine, I don’t know what’s on it. I need to figure things out fast. What’s the syntax for systemctl? How do I use journalctl to filter by time? What’s the rsync flag for dry-run?

I could google it. I could open man and search. Or I could type tldr rsync and get the answer in two seconds without leaving the terminal.

On a fresh host with no browser, no bookmarks, no history — tldr is the fastest path to “how do I do this again.”

tldr vs man

	`man`	`tldr`
Content	Complete reference	Common examples
Length	Hundreds to thousands of lines	5-8 examples
Speed	Scroll, search, parse	Read, copy, done
Offline	Always available	Needs initial cache
Edge cases	Covered	Not the point

They’re not competitors. man is the spec. tldr is the quick-start guide. I use both — but I reach for tldr first, and I reach for man when tldr wasn’t enough.

Installing it

It’s everywhere:

terminalbash

# Nix
nix-shell -p tldr

# Homebrew
brew install tldr

# npm (the original client)
npm install -g tldr

# apt
sudo apt install tldr

# Rust client (tealdeer, faster)
cargo install tealdeer

I personally use tealdeer — it’s a Rust implementation that’s faster and works offline after the first cache update. Same pages, snappier feel.

terminalbash

# First run: download the page cache
tldr --update

After that, everything works offline.

The pages

The tldr pages live in an open repository. Anyone can contribute. The quality is surprisingly high because the format enforces discipline — you can’t write a wall of text. Every entry is a short description and a handful of examples. That constraint keeps things useful.

If a page is missing or wrong, you open a PR. The turnaround is fast.

When to reach for man

tldr doesn’t try to cover everything. It covers the common cases. When you need:

Exact flag behavior and interactions
Obscure options for unusual workflows
Configuration file syntax
Exit codes and signals
Security implications of a flag

That’s man territory. tldr gets you moving. man gets you the full picture.

Stay in the terminal, stay in your head

I wrote about how autocomplete hijacks your intent — how predictive tools break your focus by inserting their guesses into your thought process. Opening a browser to look up a command is the same problem, just bigger.

You’re in the terminal. You’re in flow. You need one answer. So you open a browser tab. Now you’re looking at a search page. Autocomplete is suggesting queries. You pick a Stack Overflow link. There are three answers — the top one is outdated, the second one is for a different OS, the third one works but you had to scroll past two ads and a cookie banner to find it. By the time you’re back in the terminal, you’ve forgotten what you were actually doing.

That context switch is expensive. Not because it takes time — it does — but because it fragments your intent. You left the terminal with a clear goal. You came back with residual browser noise in your head.

tldr eliminates that entire loop. The answer stays in the terminal. Your focus stays on the task. No browser, no search engine framing your question, no feed algorithm pulling your attention sideways.

This is the same reason I built search-nix — a CLI tool that queries the search.nixos.org backend directly from the terminal. Every time I needed to find a Nix package, I’d open a browser, go to search.nixos.org, type my query, click through results, copy the package name, and switch back. That’s four context switches for a ten-character answer. Now it’s just:

terminalbash

search-nix fuser

Same philosophy. The answer belongs where the work happens. Every trip to the browser is a leak in your focus.

The workflow

It’s dead simple. You don’t remember a command’s syntax. You type:

terminalbash

tldr <command>

You get examples. You copy the one that matches. You move on.

No context switch. No browser tab. No Stack Overflow thread with three wrong answers before the right one. Just the answer, in your terminal, in under a second.

That’s why it’s the first thing I install.