Tealdeer: Introduction

Tealdeer is a very fast implementation of tldr in Rust: Simplified, example based and community-driven man pages.


This documentation shows how to install, use and configure tealdeer.



There are a few different ways to install tealdeer:

Additionally, when not using system packages, you can manually install autocompletions.

Package Managers

Tealdeer has been added to a few package managers:

Static Binaries (Linux)

Static binary builds (currently for Linux only) are available on the GitHub releases page. Simply download the binary for your platform and run it!

Through cargo install

Build and install the tool via cargo...

$ cargo install tealdeer

Build From Source

Release build:

$ cargo build --release

Release build with bundled CA roots:

$ cargo build --release --no-default-features --features webpki-roots

Debug build with logging support:

$ cargo build --features logging

(To enable logging at runtime, export the RUST_LOG=tldr=debug env variable.)


Shell completion scripts are located in the folder completion. Just copy them to their designated location:

  • Bash: cp completion/bash_tealdeer /usr/share/bash-completion/completions/tldr
  • Fish: cp completion/fish_tealdeer ~/.config/fish/completions/tldr.fish
  • Zsh: cp completion/zsh_tealdeer /usr/share/zsh/site-functions/_tldr


Tealdeer is straightforward to use, through the binary named tldr.

You can view the available options using tldr --help:

tealdeer 1.6.1
Danilo Bargen <mail@dbrgn.ch>, Niklas Mohrin <dev@niklasmohrin.de>
A fast TLDR client

    tldr [OPTIONS] [COMMAND]...

    <COMMAND>...    The command to show (e.g. `tar` or `git log`)

    -l, --list                    List all commands in the cache
    -f, --render <FILE>           Render a specific markdown file
    -p, --platform <PLATFORMS>    Override the operating system [possible values: linux, macos,
                                  windows, sunos, osx, android]
    -L, --language <LANGUAGE>     Override the language
    -u, --update                  Update the local cache
        --no-auto-update          If auto update is configured, disable it for this run
    -c, --clear-cache             Clear the local cache
        --pager                   Use a pager to page output
    -r, --raw                     Display the raw markdown instead of rendering it
    -q, --quiet                   Suppress informational messages
        --show-paths              Show file and directory paths used by tealdeer
        --seed-config             Create a basic config
        --color <WHEN>            Control whether to use color [possible values: always, auto,
    -v, --version                 Print the version
    -h, --help                    Print help information

To view the user documentation, please visit https://dbrgn.github.io/tealdeer/.

Custom Pages and Patches

Tealdeer allows creating new custom pages, overriding existing pages as well as extending existing pages.

The directory, where these custom pages and patches can be placed, follows OS conventions. On Linux for instance, the default location is ~/.local/share/tealdeer/pages/. To print the path used on your system, simply run tldr --show-paths.

The custom pages directory can be overridden by the config file.

Custom Pages

To document internal command line tools, or if you want to replace an existing tldr page with one that's better suited for you, place a file with the name <command>.page in the custom pages directory. When calling tldr <command>, your custom page will be shown instead of the upstream version in the cache.





Custom Patches

Sometimes you don't want to fully replace an existing upstream page, but just want to extend it with your own examples that you frequently need. In this case, use a file called <command>.patch, it will be appended to existing pages.






Tealdeer can be customized with a config file in TOML format called config.toml.

Configfile Path

The configuration file path follows OS conventions (e.g. $XDG_CONFIG_HOME/tealdeer/config.toml on Linux). The paths can be queried with the following command:

$ tldr --show-paths

Creating the config file can be done manually or with the help of tldr:

$ tldr --seed-config

On Linux, this will usually be ~/.config/tealdeer/config.toml.

Config Example

Here's an example configuration file. Note that this example does not contain all possible config options. For details on the things that can be configured, please refer to the subsections of this documentation page (display, style, updates or directories).

compact = false
use_pager = true

foreground = "red"

foreground = "green"

foreground = "blue"

foreground = "blue"
underline = true

auto_update = true

Override Config Directory

The directory where the configuration file resides may be overwritten by the environment variable TEALDEER_CONFIG_DIR. Remember to use an absolute path. Variable expansion will not be performed on the path.

Section: [display]

In the display section you can configure the output format.


Specifies whether the pager should be used by default or not (default false).

use_pager = true

When enabled, less -R is used as pager. To override the pager command used, set the PAGER environment variable.

NOTE: This feature is not available on Windows.


Set this to enforce more compact output, where empty lines are stripped out (default false).

compact = true

Section: [style]

Using the config file, the style (e.g. colors or underlines) can be customized.

Screenshot of customized version

Style Targets

  • description: The initial description text
  • command_name: The command name as part of the example code
  • example_text: The text that describes an example
  • example_code: The example itself (except the command_name and example_variable)
  • example_variable: The variables in the example


  • foreground (color string, ANSI code, or RGB, see below)
  • background (color string, ANSI code, or RGB, see below)
  • underline (true or false)
  • bold (true or false)
  • italic (true or false)

Colors can be specified in one of three ways:

  • Color string (black, red, green, yellow, blue, magenta, cyan, white):


    foreground = "green"
  • 256 color ANSI code (tealdeer v1.5.0+)


    foreground = { ansi = 4 }
  • 24-bit RGB color (tealdeer v1.5.0+)


    background = { rgb = { r = 255, g = 255, b = 255 } }

Section: [updates]

Automatic updates

Tealdeer can refresh the cache automatically when it is outdated. This behavior can be configured in the updates section and is disabled by default.


Specifies whether the auto-update feature should be enabled (defaults to false).

auto_update = true


Duration, since the last cache update, after which the cache will be refreshed (defaults to 720 hours). This parameter is ignored if auto_update is set to false.

auto_update = true
auto_update_interval_hours = 24

Section: [directories]

This section allows overriding some directory paths.


Override the cache directory. Remember to use an absolute path. Variable expansion will not be performed on the path. If the directory does not yet exist, it will be created.

cache_dir = "/home/myuser/.tealdeer-cache/"

If no cache_dir is specified, tealdeer will fall back to a location that follows OS conventions. On Linux, it will usually be at ~/.cache/tealdeer/. Use tldr --show-paths to show the path that is being used.


Set the directory to be used to look up custom pages. Remember to use an absolute path. Variable expansion will not be performed on the path.

custom_pages_dir = "/home/myuser/custom-tldr-pages/"

Tips and Tricks

This page features some example use cases of Tealdeer.

Showing a random page on shell start

To display a randomly selected page, you can invoke tldr twice: One time to select a page and a second time to display this page. To randomly select a page, we use shuf from the GNU coreutils:

tldr --quiet $(tldr --quiet --list | shuf -n1)

You can also add the above command to your .bashrc (or similar shell configuration file) to display a random page every time you start a new shell session.

Displaying all pages with their summary

If you want to extend the output of tldr --list with the first line summary of each page, you can run the following Python script:

#!/usr/bin/env python3

import subprocess

commands = subprocess.run(
    ["tldr", "--quiet", "--list"],

for command in commands:
    output = subprocess.run(
        ["tldr", "--quiet", command],
    description = output.lstrip().split("\n\n")[0]
    description = " ".join(description.split())
    print(f"{command} => {description}")

Note that there are a lot of pages and the script will run Tealdeer once for every page, so the script may take a couple of seconds to finish.

Extending this chapter

If you have an interesting setup with Tealdeer, feel free to share your configuration on our Github repository.