# tldr-pages — Simplified, Community-Driven Man Pages

> tldr-pages replaces cryptic man pages with practical examples. Type `tldr tar` and see the 5 commands you actually use — no more scrolling through 50 flags you will never touch.

## Install

Save in your project root:

# tldr-pages — Practical Man Pages

## Quick Use
```bash
# Install a client (there are many)
brew install tldr              # or: tealdeer (Rust, fastest)
brew install tealdeer && alias tldr=tldr

# Use it
tldr tar
tldr git commit
tldr ffmpeg
tldr --update  # refresh local cache
```

## Introduction
tldr-pages is a community-curated collection of simplified command-line documentation. Where `man tar` shows you 500 lines of options, `tldr tar` shows the 5 common invocations with real-world examples. Started in 2013, the project now has pages for 10,000+ commands in 30+ languages.

With over 62,000 GitHub stars (on the content repo alone, excluding client implementations), tldr-pages is one of the most-beloved documentation projects. Contributions from thousands of developers keep it current as tools evolve.

## What tldr-pages Does
tldr-pages is a content repository of Markdown files, one per command. Client programs (tldr, tealdeer, tlrc, tldr-python, etc.) download a ZIP of the pages, cache them locally, and render them as colored terminal output. No network calls happen on each query — the cache updates periodically.

## Architecture Overview
```
[GitHub content repo]
   pages/common/tar.md, pages/linux/systemctl.md, ...
        |
   [Release pipeline]
   bundles pages into a ZIP
        |
   CDN: tldr.sh/assets/tldr.zip
        |
   [Client: tldr / tealdeer / tlrc / ...]
   fetches + caches locally
        |
   [Rendered colored output]
```

## Self-Hosting & Configuration
```bash
# Tealdeer (Rust) — the fastest client, recommended
cargo install tealdeer
# Config: ~/.config/tealdeer/config.toml
cat > ~/.config/tealdeer/config.toml <<EOF
[display]
compact = false
use_pager = false
[updates]
auto_update = true
auto_update_interval_hours = 168
[style.description]
foreground = "white"
EOF

# Contribute a new page
git clone https://github.com/tldr-pages/tldr
# Create pages/common/mytool.md with the format below:
```

```markdown
# mytool

> Short description of what the command does.
> More information: <https://example.com>.

- Do the common thing:

`mytool -a {{value}}`

- Do another common thing with a file argument:

`mytool --file {{path/to/file}}`
```

## Key Features
- **10,000+ commands** — broad coverage of Unix + Windows + cloud tools
- **Practical examples** — 5–7 common invocations, not exhaustive flag lists
- **Offline cache** — queries are instant, no network needed
- **Multi-language** — content translated into 30+ languages
- **Multiple clients** — pick tealdeer (Rust), tlrc (Rust), tldr (Node), many more
- **Platform-specific pages** — linux/, macos/, windows/, common/
- **Community-maintained** — easy GitHub PR to contribute
- **CC BY 4.0** — free content for any use

## Comparison with Similar Tools
| Feature | tldr-pages | man | cheat.sh | bro | navi |
|---|---|---|---|---|---|
| Source | Community Markdown | Project maintainers | Aggregated | Snippets | Cheatsheets |
| Offline | Yes | Yes | No (URL) | Yes | Yes |
| Format | Examples | Reference | Examples + tables | Shell one-liners | Interactive |
| Language filter | Yes | No | Yes | No | No |
| Client-agnostic | Yes (many) | Only `man` | HTTP client | One client | One CLI |
| Best For | Quick recall | Deep reference | Mixed recall | Short tips | Interactive cheatsheets |

## FAQ
**Q: Which client should I install?**
A: `tealdeer` (Rust) is widely recommended — fast startup, clean output, easy config. On macOS, the `tldr` Homebrew formula is also fine.

**Q: Can I use tldr offline on a plane?**
A: Yes, as long as you've run `tldr --update` at least once. Pages are cached locally.

**Q: How do I contribute?**
A: Fork the repo, edit or add a page in `pages/common/` (or platform-specific folder), and open a PR. Contributor guidelines in CONTRIBUTING.md.

**Q: Why not just use `man`?**
A: `man` is authoritative reference; tldr is practical recall. Use both — tldr when you want the 5 common invocations, man when you need the full option matrix.

## Sources
- GitHub: https://github.com/tldr-pages/tldr
- Website: https://tldr.sh
- License: CC BY 4.0 (content), MIT (tooling)

---
Source: https://tokrepo.com/en/workflows/a5b995ee-380a-11f1-9bc6-00163e2b0d79
Author: AI Open Source