tldr-pages — User Guide

1. Quick Start

tldr-pages is a community-driven collection of simplified help pages for command-line tools. Each page distills a command's most common use cases into practical, copy-paste examples — replacing the wall of text you get from man pages with something you can read in seconds.

Key features:

• Concise, example-driven help pages for thousands of commands
• Coverage across 11 platforms: Linux, macOS, Windows, Android, FreeBSD, OpenBSD, NetBSD, SunOS, DOS, Cisco IOS, and cross-platform ("common")
• Translations in 40+ languages (Arabic, Bengali, Chinese, French, German, Hindi, Japanese, Korean, Portuguese, Russian, Spanish, and many more)
• Standardized page format enforced by automated linting
• PDF generation for offline reading
• Community-maintained with open contribution process
• Available through dozens of tldr client applications

Prerequisites: A tldr client installed on your system.

Try it now (using any installed tldr client):

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 path/to/target.tar path/to/file1 path/to/file2 ...

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

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

Tip

Don't have a client yet? See the Installation section below for options, or browse pages directly at tldr.sh.

What to try next:

• Install a tldr client for your platform
• Browse available pages by platform
• Contribute a new page or translation

2. Installation

System Requirements

tldr-pages is a content repository — the pages themselves have no runtime dependencies. You need a tldr client to read them from the command line.

Installing a tldr Client

There are dozens of tldr clients for every platform and language. The most popular:

Node.js

npm install -g tldr

Python (tldr)

pip install tldr

Rust (tealdeer)

cargo install tealdeer

Homebrew

brew install tldr

Android (Termux)

pkg install tldr

Important

The tldr-pages/tldr repository is the page collection, not a client. You need a separate client application to read pages. See the full client list at the tldr-pages clients wiki.

Verifying Your Installation

After installing a client, verify it works:

tldr --version

Then fetch the page index:

tldr --update

Successfully updated local database

Cloning the Repository (for Contributors)

If you want to contribute pages or run the maintenance scripts:

git clone https://github.com/tldr-pages/tldr.git
cd tldr
npm install

Note

Git and Python must be installed to run the repository scripts locally. Node.js 20+ is required for the linting tools.

Install Troubleshooting

Error: command not found: tldr

Cause: The client binary is not in your PATH.

Solution:

1. Verify the install location: which tldr or where tldr
2. Add the binary directory to your PATH
3. Restart your terminal session

Prevention: Use a package manager that handles PATH automatically (Homebrew, apt, npm global).

Error: Page not found

Cause: Local page cache is out of date or the command does not have a tldr page yet.

Solution:

1. Update the cache: tldr --update
2. Search for the command: tldr --search keyword
3. If no page exists, consider contributing one

Error: npm install fails during contributor setup

Cause: Node.js version too old or network issues.

Solution:

1. Verify Node.js version: node --version (20+ required)
2. Clear npm cache: npm cache clean --force
3. Retry: npm install

3. Configuration

Page Format Specification

Every tldr page follows a strict format. Understanding it helps you read and contribute pages effectively.

A page consists of:

# command-name

> Brief description of the command.
> More information: <https://example.com/docs>.

- Description of example 1:

`command --option argument`

- Description of example 2:

`command --other-option`

Platform Organization

Pages are organized by platform in the repository:

Tip

Most tldr clients automatically select the right platform for your OS. Use tldr --platform linux docker to view pages for a different platform.

Translation Directories

Translated pages live in pages.{language_code}/ directories (e.g., pages.es/ for Spanish, pages.zh/ for Chinese). Each translation directory mirrors the platform structure of the English pages/ directory.

Note

See the Admin Guide for the complete .markdownlint.json configuration reference and linting tool details.

4. Core Usage

Reading Pages

The primary use case — looking up how to use a command:

tldr tar

View a page for a specific platform:

tldr --platform osx brew

List all available pages:

tldr --list

Searching for Commands

Most clients support keyword search:

tldr --search "compress files"

Browsing Online

The complete collection is browsable at:

• Website: tldr.sh
• GitHub: github.com/tldr-pages/tldr
• PDF books: Generated per-language from the repository (see PDF Generation below)

Warning

Some older tldr clients may not support all platforms (e.g., Cisco IOS, DOS). Update to the latest client version if pages appear missing.

Generating PDF Books

The repository includes a Python script to render all pages for a language into a single PDF:

cd scripts/pdf
pip install -r requirements.txt
python3 render.py ../../pages -c solarized-light -o tldr-book.pdf

Rendered page 1 of the directory common
Rendered page 2 of the directory common
...
Converting all pages to PDF...
Created tldr-book.pdf in the current directory!

Important

The render.py script requires Python 3 with the markdown and weasyprint packages. WeasyPrint has system-level dependencies (GTK, Pango, Cairo) — see WeasyPrint installation docs for your platform.

PDF CLI Options

Generate a PDF for only the Linux platform:

python3 render.py ../../pages -c basic -p linux -o tldr-linux.pdf

Generate a PDF for a specific translation:

python3 render.py ../../pages.es -c basic -o tldr-book-es.pdf

Note

PDF generation for CJK languages (Bengali, Japanese, Korean, Malayalam, Tamil, Thai, Chinese, Chinese Traditional) is currently not supported via build-pdf.sh due to font rendering limitations. You can still use render.py directly for these languages if you have appropriate fonts installed.

5. Common Tasks

Contributing a New Page

Goal: Add a tldr page for a command that doesn't have one yet.

Prerequisites: Git, a GitHub account, familiarity with the page format.

Steps:

1. Check if the page already exists:

   find pages/ -name "command-name.md"
   

2. Determine the correct platform directory (pages/common/, pages/linux/, etc.)

3. Create the page file:

   touch pages/common/command-name.md
   

4. Write the page following the format specification (see Configuration section)

5. Run the linter:

   npm run lint-tldr-pages
   

6. Submit a pull request

Verify: The CI checks (test.sh, check-pr.sh) run automatically on your PR.

If it fails: Fix linting errors reported by tldr-lint and markdownlint.

Translating a Page

Goal: Add a translation for an existing English page.

Steps:

1. Find the English page you want to translate (e.g., pages/common/tar.md)

2. Create the matching file in the appropriate language directory:

   mkdir -p pages.fr/common/
   cp pages/common/tar.md pages.fr/common/tar.md
   

3. Translate the description and example descriptions (keep command syntax unchanged)

4. Run the linter and submit a PR

Tip

Translation templates are available in contributing-guides/translation-templates/ to help maintain consistent phrasing across pages within a language.

Creating an Alias Page

Goal: Create a page that redirects to another command (e.g., gtar → tar).

Use the provided script:

python3 scripts/set-alias-page.py

This generates or updates alias pages that point readers to the canonical command page.

Updating "More Information" Links

Goal: Add or update the documentation URL across pages.

python3 scripts/set-more-info-link.py

Updating "See Also" References

Goal: Add cross-references between related commands.

python3 scripts/set-see-also.py

Checking for Common Errors

Goal: Find common formatting issues in a language directory.

cd pages.es
../scripts/check-errors.sh

Warning

check-errors.sh uses grep patterns to find common mistakes. It is not a substitute for the full lint suite (npm run lint-markdown + npm run lint-tldr-pages).

Building the Page Index

Goal: Generate the index.json file listing all available pages.

npm run build-index

Building ZIP Archives

Goal: Package pages for distribution.

bash scripts/build.sh

Note

build.sh and build-pdf.sh are Linux/macOS only. On Windows, use WSL.

6. Troubleshooting

Linting Errors

Error: TLDR003 — Description too long

Cause: A description line exceeds the maximum length.

Solution:

1. Shorten the description to fit within the line limit
2. Split into two > lines if needed

Prevention: Keep descriptions concise — tldr pages are meant to be brief.

Error: TLDR014 — Page title doesn't match filename

Cause: The # title heading doesn't match the filename (without .md).

Solution:

1. Rename the file or update the title to match
2. Use python3 scripts/wrong-filename.py to detect mismatches across the repository

Prevention: Always name the file exactly after the command.

Error: MD013 — Line length warnings

Cause: A line exceeds 250 characters (configured in .markdownlint.json).

Solution: Break long lines at natural points.

PDF Generation Issues

Error: ModuleNotFoundError: No module named 'weasyprint'

Cause: Python dependencies not installed.

Solution:

cd scripts/pdf
pip install -r requirements.txt

Error: Invalid directory. Please try again!

Cause: The dir_path argument doesn't point to a valid pages directory.

Solution: Verify the path is correct and points to a pages* directory:

python3 render.py ../../pages -c basic

Error: WeasyPrint OSError or missing system libraries

Cause: WeasyPrint requires system-level libraries (GTK3, Pango, Cairo, GDK-PixBuf).

Solution:

Debian/Ubuntu

sudo apt install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0

macOS

brew install pango gdk-pixbuf libffi

Windows

Install GTK3 runtime or use WSL

Prevention: Install system dependencies before pip install weasyprint.

Contribution Workflow Issues

PR checks fail with check-pr.sh errors

Cause: Page syntax doesn't conform to tldr-pages standards.

Solution:

1. Run locally: bash scripts/test.sh
2. Fix all reported issues
3. Push the fixes

Prevention: Run npm run lint-tldr-pages before committing. The husky pre-commit hook runs automatically if installed via npm install.

Error: husky - command not found

Cause: Dev dependencies not installed.

Solution:

npm install

Caution

Never bypass the pre-commit hook with --no-verify. The CI will catch the same issues and block your PR.

7. FAQ

Q: What is the difference between tldr-pages/tldr and a "tldr client"?

tldr-pages/tldr is the GitHub repository containing the actual help pages — thousands of Markdown files organized by platform and language. A tldr client is a separate application (like tealdeer, tldr-node-client, or tldr-python-client) that downloads and displays those pages in your terminal. Think of it like Wikipedia (the content) versus a web browser (the viewer).

Q: How do I request a page for a command that doesn't have one?

Open an issue on GitHub with the title "Page request: command-name". The community tracks requests — recent examples include requests for sqlfluff (#22164), ukify (#22190), and mcopy (#21939).

Q: Can I contribute pages in my language?

Yes. Translations live in pages.{language_code}/ directories. Check the contributing-guides/translation-templates/ folder for standardized phrasing in your language. If your language doesn't have a directory yet, create one following the existing pattern.

Q: How many pages and languages does tldr-pages cover?

The repository contains over 35,000 files across 40+ language translations and 11 platforms. The English pages/ directory is the most complete, with translated directories at varying levels of coverage.

Q: What platforms are supported?

Linux, macOS (osx), Windows, Android, FreeBSD, OpenBSD, NetBSD, SunOS/Solaris, DOS, and Cisco IOS — plus a common category for cross-platform commands.

Q: Where should I put a page for a cross-platform command?

In pages/common/. Only use platform-specific directories for commands that genuinely exist only on that platform or behave very differently across platforms.

Q: How do I update a command's examples across all translations?

Use the update-command.py script:

python3 scripts/update-command.py

This updates the common content of a command example across all language versions.

Q: What's the page limit for examples?

A maximum of 8 examples per page. Keep examples focused on the most common use cases.

Q: Are there plans to document Zsh builtins and terminal games?

Yes — these are tracked as open community initiatives. See issue #21002 (Zsh builtins) and #22118 (terminal games).