# 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](https://github.com/tldr-pages/tldr/wiki/tldr-pages-clients) installed on your system.

**Try it now** (using any installed tldr client):

```bash
tldr tar
```

```text
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](https://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.

| Requirement | Detail |
|---|---|
| Any OS | Linux, macOS, Windows, Android, FreeBSD, and more |
| A tldr client | Required to display pages in the terminal |
| Git (optional) | Only needed for contributing or building from source |

### Installing a tldr Client

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

=== "Node.js"
    ```bash
    npm install -g tldr
    ```

=== "Python (tldr)"
    ```bash
    pip install tldr
    ```

=== "Rust (tealdeer)"
    ```bash
    cargo install tealdeer
    ```

=== "Homebrew"
    ```bash
    brew install tldr
    ```

=== "Android (Termux)"
    ```bash
    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](https://github.com/tldr-pages/tldr/wiki/tldr-pages-clients).

### Verifying Your Installation

After installing a client, verify it works:

```bash
tldr --version
```

Then fetch the page index:

```bash
tldr --update
```

```text
Successfully updated local database
```

### Cloning the Repository (for Contributors)

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

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

> [!NOTE]
> [Git](https://git-scm.com/) and [Python](https://www.python.org/) 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:

```markdown
# 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`
```

| Element | Rule |
|---|---|
| Title | `# command-name` — matches the filename |
| Description | `> ` blockquote, 1-3 lines |
| More info link | `> More information: <URL>.` — always present |
| Examples | `-` description line, followed by backtick-wrapped command |
| Max examples | 8 per page |
| Placeholders | `path/to/file`, `string`, `command` — never literal values |

### Platform Organization

Pages are organized by platform in the repository:

| Directory | Platform | Scope |
|---|---|---|
| `pages/common/` | Cross-platform | Commands available on most systems |
| `pages/linux/` | Linux | Linux-specific commands |
| `pages/osx/` | macOS | macOS-specific commands |
| `pages/windows/` | Windows | Windows/CMD/PowerShell commands |
| `pages/android/` | Android (Termux) | Android-specific commands |
| `pages/sunos/` | SunOS/Solaris | SunOS-specific commands |
| `pages/freebsd/` | FreeBSD | FreeBSD-specific commands |
| `pages/openbsd/` | OpenBSD | OpenBSD-specific commands |
| `pages/netbsd/` | NetBSD | NetBSD-specific commands |
| `pages/dos/` | DOS | DOS-specific commands |
| `pages/cisco-ios/` | Cisco IOS | Cisco network equipment commands |

> [!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:

```bash
tldr tar
```

View a page for a specific platform:

```bash
tldr --platform osx brew
```

List all available pages:

```bash
tldr --list
```

### Searching for Commands

Most clients support keyword search:

```bash
tldr --search "compress files"
```

### Browsing Online

The complete collection is browsable at:

- **Website:** [tldr.sh](https://tldr.sh)
- **GitHub:** [github.com/tldr-pages/tldr](https://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:

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

```text
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](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) for your platform.

#### PDF CLI Options

| Option | Type | Default | Description |
|---|---|---|---|
| `dir_path` | string | *(required)* | Path to the `pages` directory to render |
| `-c` / `--color` | string | `basic` | Color scheme: `basic`, `solarized-light`, or `solarized-dark` |
| `-o` / `--output` | string | `tldr-book.pdf` | Custom output filename |
| `-p` / `--platform` | string(s) | *(all)* | One or more platforms to include (e.g., `common linux`) |

**Generate a PDF for only the Linux platform:**

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

**Generate a PDF for a specific translation:**

```bash
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:
   ```bash
   find pages/ -name "command-name.md"
   ```

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

3. Create the page file:
   ```bash
   touch pages/common/command-name.md
   ```

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

5. Run the linter:
   ```bash
   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:
   ```bash
   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:

```bash
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.

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

### Updating "See Also" References

**Goal:** Add cross-references between related commands.

```bash
python3 scripts/set-see-also.py
```

### Checking for Common Errors

**Goal:** Find common formatting issues in a language directory.

```bash
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.

```bash
npm run build-index
```

### Building ZIP Archives

**Goal:** Package pages for distribution.

```bash
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:**
```bash
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:
```bash
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"
    ```bash
    sudo apt install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0
    ```

=== "macOS"
    ```bash
    brew install pango gdk-pixbuf libffi
    ```

=== "Windows"
    ```text
    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:**
```bash
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:

```bash
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).

---

_Generated May 2026 from tldr-pages/tldr at 6145185. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._