tldr Cheat Sheet

Overview

tldr (Too Long; Didn’t Read) is a collection of community-maintained help pages for command-line tools. Unlike traditional man pages, tldr pages focus on practical examples that cover the most common use cases. Each page is concise, typically showing 5-8 examples with clear descriptions of what each command does.

The tldr pages project is open source with contributions from thousands of developers. It covers pages for Linux, macOS, Windows, and platform-agnostic commands. Multiple client implementations exist in various languages including Node.js, Python, Rust, Go, and C, all accessing the same shared page repository.

Installation

Node.js Client (Official)

npm install -g tldr

Python Client (tldr-py)

pip install tldr

Rust Client (tealdeer) — Fastest

# macOS
brew install tealdeer

# Arch Linux
sudo pacman -S tealdeer

# Cargo
cargo install tealdeer

# Ubuntu/Debian (download binary)
curl -Lo /usr/local/bin/tldr \
  https://github.com/dbrgn/tealdeer/releases/latest/download/tealdeer-linux-x86_64-musl
chmod +x /usr/local/bin/tldr

Go Client

go install github.com/isacikgoz/tldr/cmd/tldr@latest

Other Package Managers

# macOS (Homebrew)
brew install tldr

# Ubuntu/Debian
sudo apt install tldr

# Arch Linux
sudo pacman -S tldr

# Nix
nix-env -iA nixpkgs.tldr

# Android (Termux)
pkg install tldr

Core Commands

Basic Usage

Command	Description
`tldr tar`	Show tldr page for tar
`tldr git commit`	Show tldr page for git subcommand
`tldr --update`	Update the local page cache
`tldr --list`	List all available pages
`tldr --search "compress"`	Search for pages matching a keyword
`tldr --platform linux tar`	Show Linux-specific page
`tldr --platform osx pbcopy`	Show macOS-specific page
`tldr --language es tar`	Show page in Spanish

Platform Selection

# View page for a specific platform
tldr --platform linux systemctl
tldr --platform osx defaults
tldr --platform windows choco
tldr --platform sunos zfs

# Common platform aliases (tealdeer)
tldr --platform linux iptables
tldr -p osx diskutil

Cache Management

# Update local cache (download latest pages)
tldr --update

# Clear the cache
tldr --clear-cache

# tealdeer: check cache age
tldr --update
# Auto-updates if cache is older than configured max age

Configuration

Tealdeer Configuration

# Create config file
mkdir -p ~/.config/tealdeer
cat > ~/.config/tealdeer/config.toml << 'EOF'
[display]
use_pager = false
compact = false

[style.command_name]
foreground = "cyan"
bold = true

[style.example_text]
foreground = "green"

[style.example_code]
foreground = "cyan"

[style.example_variable]
foreground = "cyan"
underline = true

[updates]
auto_update = true
auto_update_interval_hours = 720

[directories]
custom_pages_dir = "~/.local/share/tldr/custom"
EOF

Node.js Client Configuration

# Set environment variables
export TLDR_CACHE_MAX_AGE=720    # Cache max age in hours
export TLDR_LANGUAGE="en"         # Default language
export TLDR_PLATFORM="linux"      # Default platform

Shell Aliases

# Add to ~/.bashrc or ~/.zshrc
alias help='tldr'
alias h='tldr'

# Fuzzy search with fzf
alias tldrf='tldr --list | fzf --preview "tldr {1}" | xargs tldr'

Advanced Usage

Custom Pages

# Create a custom pages directory
mkdir -p ~/.local/share/tldr/custom/pages

# Create a custom page
cat > ~/.local/share/tldr/custom/pages/my-script.md << 'EOF'
# my-script

> Custom deployment script for the project.
> More information: <https://internal-docs.example.com>.

- Deploy to staging:

`my-script deploy --env staging`

- Deploy to production with confirmation:

`my-script deploy --env production --confirm`

- Rollback to the previous version:

`my-script rollback --env {{environment}}`

- Check deployment status:

`my-script status --env {{environment}}`
EOF

Page Format Specification

# command-name

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

- Description of example 1:

`command --option {{argument}}`

- Description of example 2:

`command {{file1}} {{file2}}`

- Description with piped command:

`command {{input}} | other-command`

Fuzzy Finding with fzf

# Interactive tldr browser
tldr_fzf() {
  local page
  page=$(tldr --list | fzf \
    --preview "tldr {1} --color always" \
    --preview-window=right:70%:wrap)
  if [ -n "$page" ]; then
    tldr "$page"
  fi
}

# Add to shell config
alias ti='tldr_fzf'

Contributing Pages

# Fork and clone the tldr repository
git clone https://github.com/tldr-pages/tldr.git
cd tldr

# Create or edit a page
# Pages go in: pages/<platform>/command-name.md
# Platforms: common, linux, osx, windows, sunos, android

# Example: new page for a common command
cat > pages/common/my-command.md << 'EOF'
# my-command

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

- Basic usage:

`my-command {{filename}}`

- Use a specific flag:

`my-command --verbose {{filename}}`
EOF

# Lint the page
npm install
npm run lint

# Submit a pull request
git checkout -b add-my-command
git add pages/common/my-command.md
git commit -m "my-command: add page"
git push origin add-my-command

Multiple Languages

# View a page in a different language
tldr --language es git
tldr --language fr docker
tldr --language de tar
tldr --language zh curl
tldr --language ja grep

# Available languages vary by page
# Falls back to English if translation not available

Shell Completions

# Bash completions (tealdeer)
tldr --seed-config
source <(tldr --generate-completions bash)

# Zsh completions
tldr --generate-completions zsh > ~/.zfunc/_tldr

# Fish completions
tldr --generate-completions fish > ~/.config/fish/completions/tldr.fish

Troubleshooting

Issue	Solution
”Page not found”	Run `tldr --update` to refresh the cache
Cache outdated	Clear and re-download: `tldr --clear-cache && tldr --update`
Slow first lookup	Initial cache download can take a moment; subsequent lookups are instant
No colors in output	Check terminal color support; use `--color always` flag
Wrong platform shown	Specify platform explicitly: `tldr --platform linux command`
Client version conflicts	Uninstall duplicate clients; use only one (tealdeer recommended for speed)
Custom pages not showing	Verify `custom_pages_dir` path in config matches where files are stored
Permission denied on install	Use `sudo` for system-wide install or install to user directory
Language fallback not working	Ensure pages exist in the requested language; check with `tldr --list`