# tldr for console commands: example pages, four official clients, and a spec that moves separately

> tldr-pages/tldr is a repository of Markdown cheatsheets for command line tools, not a program you run. What you actually read depends on which of four client projects you install, and those clients implement a specification that has been versioned three times since 2023.

**tldr-pages/tldr** — GitHub describes it as Collaborative cheatsheets for console commands 📚.. The repository metadata lists Markdown as its primary language. The metadata lists the NOASSERTION license. This article stays within the project description and details documented in the GitHub repository README.

- Repository: https://github.com/tldr-pages/tldr
- Website: https://tldr.sh
- Stars: 63,787 · Forks: 5,433
- Language: Markdown
- License: NOASSERTION
- Published: 2026-08-13 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/tldr-pages-tldr

## One Markdown file per command, spread across thirty-nine language directories

tldr-pages/tldr ships no executable of its own. The repository root holds thirty-nine pages.<lang> directories alongside a plain pages/ directory, and every Markdown file inside one of them is a single command's help page. English sits in pages.en, Japanese in pages.ja, Simplified Chinese in pages.zh.

Each language is a separate copy rather than an overlay, so a translation can drift away from the English page it was made from, and pages can be missing from one language while present in another. The tldri18n site is where the project tracks exactly that, showing which translations are missing or outdated.

Because pages are found by command name, something has to know the filenames. package.json carries a build-index script, and index.json does not appear in the top-level file listing, so the index is generated at build time rather than committed. Clients do not read this repository while you type; the project ships four separate client projects for that job.

## pipx, brew, cargo, winget and npm each reach a different client

The pages are read through a client, and the four official ones are separate projects with different languages. The Python client installs from PyPI through pipx:

```bash
pipx install tldr
```

Linux and macOS users can take the Rust client instead, through Homebrew or Cargo:

```bash
brew install tlrc
```

```bash
cargo install tlrc --locked
```

On Windows the same Rust client comes from Winget:

```bash
winget install tldr-pages.tlrc
```

The Node.js client has the shortest install of the four, and the project is blunt about its state:

```bash
npm install -g tldr
```

Once a client is installed, the command takes a tool name where the man command takes a page section:

```bash
tldr tar
```

Two routes need no install at all: a browser client at https://tldr.inbrowser.app that works offline as a PWA, and a PDF pulled from the release assets. Which one you pick matters more than it first appears, because the four clients are independent projects on their own schedules.

## The client spec ships releases of its own, and v2.3 sets an asset deprecation date

CLIENT-SPECIFICATION.md at the repository root is the contract between pages and clients, and it is versioned on a schedule of its own. Three tagged releases carry it. v2.1 on 2023-11-30 added escaping placeholder syntax and automatic platform detection. v2.2 on 2024-03-20 changed the cache asset URLs. v2.3 on 2025-03-07 added option placeholders and set a deprecation date for the old asset website. None of the three added a new client or a new platform.

That separation is the thing to understand before you write either side of it. A page that uses placeholder rules from a recent specification can render wrongly in a client built to the v2.1 rules. A client still fetching the v2.1 cache URLs is fetching from a site that v2.3 places on a deprecation clock, so the failure arrives later and looks like a network problem rather than a version problem.

The pages themselves are not in doubt. The last push to the repository was on 2026-09-29.

## tldr-lint and markdownlint decide whether a page is mergeable

A page does not merge on taste alone. package.json wires the checks, and the contributor path runs through them:

```json
"scripts": {
  "lint-markdown": "markdownlint pages*/**/*.md",
  "lint-tldr-pages": "tldr-lint ./pages",
  "test": "bash scripts/test.sh",
  "build-index": "node ./scripts/build-index.js > index.json",
  "prepare": "husky"
}
```

tldr-lint is the tool named for the page format itself, while markdownlint only knows Markdown rules. The tldr-lint dependency sits at ^0.0.23, and a 0.0.x pin is the shape a project uses while its format is still changing, so a lint failure can appear with no change to your page. markdownlint-cli is on the looser ^0.49.1 range, which means a local run can disagree with the run behind the Build status badge.

The Python side is pinned exactly instead, in requirements.txt: black==26.5.1, flake8==7.4.1 and requests==2.34.2. husky is wired to prepare, so a plain install of the repository can install a git hook before you expect one. Open issues carrying the help wanted label are the project's way of listing which commands people are asking for.

## No page records which version of the tool it describes

Nothing in the repository ties a page to a version of the tool it documents. Pages are Markdown files named after commands, and neither the README nor CLIENT-SPECIFICATION.md describes a version field, a minimum-version note, or any way to ask for the page matching your installed build. The lookup is by command name, so the same text comes back whether your tar still takes a blocksize option or has dropped it. The blocksize example is the exact kind of default that ages out of a manual.

The index is not filtered by platform either. One page set covers UNIX, Linux, macOS, FreeBSD, NetBSD, OpenBSD, SunOS, Android, Windows, Cisco IOS and DOS, and automatic platform detection arrived only with client specification v2.1. On a client that predates it, a page written for a Cisco IOS or DOS tool can be handed to you at a Linux shell, and nothing on the page marks which of its examples belong to your platform.

The practical consequence is that a tldr page is a prompt to look, not a contract. It tells you a flag exists somewhere in that tool's history, and you still have to find out whether your build has it.

## Offline reading means the PWA or the release PDF, not a client flag

Reading with no network is a browser or a PDF. The project points browsers at https://tldr.inbrowser.app, which it says supports offline use as a PWA, and points people who would rather install nothing at the PDF in the release assets. That PDF link resolves to the latest release rather than a fixed version, so the file you receive is whatever the newest asset happens to be on the day you click, and it gains no pages published after that release. Translations have their own PDFs, available for most languages, and those sit in the same release assets.

For the terminal clients the README documents no offline mode, no cache directory, and no flag to point at a local checkout of the pages. On an isolated machine the documented answers are the PWA and the PDF, and that is the whole list.

The Node.js client does not close the gap. It is described as having fallen behind in updates, which makes it the install with the fewest steps and the one least likely to match the placeholder and platform behaviour described in specification v2.3. Pick the Python or Rust client if you intend to keep the client current with the pages.

## cheat.sh, devhints, eg and kb each answer a different question

The project's own list of similar projects differs in approach, not in polish. cheat.sh aggregates cheatsheets from multiple sources, tldr-pages among them, into one unified interface, so it can answer for a tool tldr has no page for, and it also means you are reading a merged result assembled from sources you did not choose. devhints is not focused on the command line and covers many programming subjects, so it is broader in topic and vaguer about a single invocation.

eg takes the opposite approach from tldr. Its examples come from the repository, but it explains them on the command line and lets you display custom examples and commands alongside the defaults, which is the opposite of tldr's fixed community page. kb goes further still and is a minimalist knowledge base manager for organising your own notes and cheatsheets.

Choose on the gap. If you cannot recall which flag does what, any of these beats scrolling a man page. If you want the reasoning behind a command rather than a list of examples, eg explains where tldr only lists. If you want tldr content plus other sources behind one address, cheat.sh already folds tldr in. kb only helps when the real problem is that you have no notes of your own.

## Conclusion

Adopt tldr-pages when you half remember a command and want an example faster than a man page, and install the Python or Rust client rather than the Node.js one, which the project describes as having fallen behind in updates. Do not treat it as a man page replacement. Before trusting a page, check whether the flags it shows exist in the version of the tool on your machine, because no page in the repository records which version of the tool it describes.

## FAQ

### How do I install TLDR pages?

tldr-pages is a repository of pages rather than something you install; you read it through a client. The Python client installs from PyPI with pipx, the Rust client with Homebrew or Cargo on Linux and macOS and with Winget on Windows, and the Node.js client with npm.

### What is the TLDR command?

It is the client command that shows the page for a named tool, for example tldr tar in place of man tar. The project describes its pages as a simpler complement to man pages rather than a replacement for them.

### What is TLDR in software?

In software, tldr refers to community-maintained help pages for command line tools, written in Markdown so they can be edited and submitted as pull requests. The target reader is anyone who cannot recall the arguments for a command such as lsof or tar.

### How do I install TL;DR on Ubuntu?

For Linux the project documents the Rust client through Homebrew or Cargo and the Python client through pipx, and names no Ubuntu package. Two options need no install at all: the browser client at tldr.inbrowser.app and a PDF from the release assets.

## Sources

- [Official documentation](https://tldr.sh)
- [Official README](https://github.com/tldr-pages/tldr#readme)
- [Project repository](https://github.com/tldr-pages/tldr)
- [Release notes](https://github.com/tldr-pages/tldr/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tldr-pages-tldr