How to Use tldr for Quick Command Help

tldr is a community-maintained set of simplified man pages. Where man tar gives you eight dense screens of every flag ever added, tldr tar gives you the five examples you actually reach for. It is not a replacement for man pages—it is a fast lookup tool for the common cases, usable entirely offline once the cache is populated.

Choosing a Client

The tldr project defines a spec; several clients implement it. The most practical choices are:

• tldr (Node.js, the reference client) — widest page coverage, easiest install on any distro.
• tealdeer — single Rust binary, fastest startup, excellent offline support, available in most distro repos.
• tldr-python-client — good if Python is already your dependency anchor.

This guide covers tealdeer (package name tealdeer or tldr depending on the distro) and the Node.js client. Both read the same page cache, so the examples look identical once installed.

Installation

Debian and Ubuntu

Tealdeer is in the Ubuntu 22.04+ and Debian 12+ repos under the name tealdeer. The package installs a binary called tldr.

sudo apt update && sudo apt install tealdeer

If you prefer the Node.js client (requires Node 14+):

sudo npm install -g tldr

Fedora and RHEL / Rocky Linux

Tealdeer is in the Fedora default repos. On RHEL 9 / Rocky 9, enable EPEL first.

# Fedora
sudo dnf install tealdeer

# RHEL 9 / Rocky 9
sudo dnf install epel-release
sudo dnf install tealdeer

Arch Linux

Both clients are in the official repos or the AUR.

# tealdeer (community repo)
sudo pacman -S tealdeer

# tldr-python-client (AUR)
yay -S tldr-python-client

Any Distro via Cargo

If your distro ships an old version or lacks the package entirely, build tealdeer from source. Requires the Rust toolchain (rustup).

cargo install tealdeer

The binary lands in ~/.cargo/bin/tldr. Make sure that directory is on your PATH.

Populating the Offline Cache

Tealdeer ships with no pages bundled. The first thing to do after install is fetch the cache. This downloads the full tldr-pages archive (~4 MB) to ~/.cache/tealdeer.

tldr --update

Expected output (will vary slightly by version):

Successfully updated local cache.

After this, every lookup is fully offline—no network required. The Node.js client populates its own cache automatically on first use, or you can force it:

tldr --update

Basic Usage

Look up any command by passing its name as the argument:

tldr tar

You get a short description and several practical examples with inline annotations. Output is colour-coded in terminals that support it.

Look up a subcommand or multi-word topic with a hyphen or by quoting:

tldr git-log
tldr git log

Pages are organised by platform. Force a specific platform if the default guess is wrong:

tldr --platform linux tar
tldr --platform osx pbcopy

Searching and Listing Pages

List every available page (useful for discovering commands you did not know existed):

tldr --list

Pipe it to grep to find pages related to a topic:

tldr --list | grep -i compress

Tealdeer also supports a --search flag that searches page descriptions, not just names:

tldr --search "disk usage"

Keeping the Cache Fresh

The tldr-pages project is actively maintained—pages are added and corrected regularly. Set a reminder or automate the update. A simple systemd user timer works well.

Systemd User Timer (tealdeer)

Create the service unit:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/tldr-update.service <<'EOF'
[Unit]
Description=Update tealdeer cache

[Service]
Type=oneshot
ExecStart=/usr/bin/tldr --update
EOF

Create the timer unit (runs weekly):

cat > ~/.config/systemd/user/tldr-update.timer <<'EOF'
[Unit]
Description=Weekly tealdeer cache update

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target
EOF

Enable and start the timer:

systemctl --user daemon-reload
systemctl --user enable --now tldr-update.timer

Verify it is scheduled:

systemctl --user list-timers tldr-update.timer

Alternatively, tealdeer has a built-in auto-update option. Set auto_update_interval_hours in the config file and the binary updates the cache silently when the interval expires.

Configuration (tealdeer)

Generate the default config file:

tldr --seed-config

The config lands at ~/.config/tealdeer/config.toml. Useful knobs:

cat ~/.config/tealdeer/config.toml

Key settings to consider:

• auto_update_interval_hours — set to 168 for weekly silent updates.
• display.use_pager — set to true to pipe long pages through less.
• directories.custom_pages_dir — point to a directory of your own pages (see below).

Writing Your Own Pages

You can add local pages for internal tools or workflows. Create a directory and write a page in the tldr Markdown format:

mkdir -p ~/.local/share/tldr/pages/linux

cat > ~/.local/share/tldr/pages/linux/deploy.md <<'EOF'
# deploy

> Internal deployment script.
> More information: 

- Deploy the staging environment:

`deploy staging`

- Roll back the last release:

`deploy rollback`
EOF

Point tealdeer at the directory in config.toml:

[directories]
custom_pages_dir = "/home/youruser/.local/share/tldr"

Custom pages take precedence over official ones when names collide, so use unique names for internal tools.

Verification

Confirm everything is working correctly:

# Check the installed version
tldr --version

# Look up a common command
tldr curl

# Confirm cache location and age
tldr --show-paths

tldr --show-paths prints the cache directory and when it was last updated. If the page renders with coloured examples, the install is healthy.

Troubleshooting

• "Page not found" for a common command — run tldr --update. The cache may be empty or stale. If the page genuinely does not exist yet, check the tldr-pages GitHub repo or contribute one.
• No colour output — tealdeer respects NO_COLOR and TERM. Check echo $TERM; terminals reporting dumb get plain text. On Wayland, ensure your terminal emulator exports correct TERM values (most do by default).
• Command not found after cargo install — add ~/.cargo/bin to your PATH in ~/.bashrc or ~/.zshrc: export PATH="$HOME/.cargo/bin:$PATH".
• Node.js client fails to update behind a proxy — export HTTPS_PROXY before running tldr --update.
• Old Debian/Ubuntu repos ship a very outdated tealdeer — on Ubuntu 20.04 or Debian 11, prefer the Cargo install or grab the pre-built binary from the tealdeer releases page.