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.

Links

• GitHub Project Page
• TLDR Pages Project

Installing

There are a few different ways to install tealdeer:

• Through package managers
• Through static binaries
• Through cargo install
• By building from source

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

Package Managers

Tealdeer has been added to a few package managers:

• Arch Linux: tealdeer
• Debian: tealdeer
• Fedora: tealdeer
• FreeBSD: sysutils/tealdeer
• Funtoo: app-misc/tealdeer
• Homebrew: tealdeer
• MacPorts: tealdeer
• NetBSD: sysutils/tealdeer
• Nix: tealdeer
• openSUSE: tealdeer
• Scoop: tealdeer
• Solus: tealdeer
• Void Linux: tealdeer

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 native TLS support:

$ cargo build --release --features native-tls

Debug build with logging support:

$ cargo build --features logging

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

Autocompletion

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

Usage

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

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

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

Usage: tldr [OPTIONS] [COMMAND]...

Arguments:
  [COMMAND]...  The command to show (e.g. `tar` or `git log`)

Options:
  -l, --list                 List all commands in the cache
      --edit-page            Edit custom page with `EDITOR`
      --edit-patch           Edit custom patch with `EDITOR`
  -f, --render <FILE>        Render a specific markdown file
  -p, --platform <PLATFORM>  Override the operating system, can be specified multiple times in order
                             of preference [possible values: linux, macos, sunos, windows, android,
                             freebsd, netbsd, openbsd, common]
  -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
      --config-path <FILE>   Override config file location
      --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, never]
  -v, --version              Print the version
  -h, --help                 Print help

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

Custom Pages and Patches

⚠️ Breaking change in version 1.7.0: The file name extension for custom pages and patches was changed:

• <name>.page → <name>.page.md
• <name>.patch → <name>.patch.md

If you have custom pages or patches, you need to rename them.

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.md in the custom pages directory. When calling tldr <command>, your custom page will be shown instead of the upstream version in the cache.

Path:

$CUSTOM_PAGES_DIR/<command>.page.md

Example:

~/.local/share/tealdeer/pages/ufw.page.md

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.md, it will be appended to existing pages.

Path:

$CUSTOM_PAGES_DIR/<command>.patch.md

Example:

~/.local/share/tealdeer/pages/ufw.patch.md

Configuration

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, search, updates or directories).

[display]
compact = false
use_pager = true
show_title = false

[style.command_name]
foreground = "red"

[style.example_text]
foreground = "green"

[style.example_code]
foreground = "blue"

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

[updates]
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.

use_pager

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

[display]
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.

compact

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

[display]
compact = true

show_title

Display the command name at the top of the page output (default false).

[display]
show_title = true

When enabled, the command name will be displayed at the top of the output, styled with the command_name style configuration.

Section: [style]

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

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

Attributes

• 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):

  Example:

  foreground = "green"
  

• 256 color ANSI code (tealdeer v1.5.0+)

  Example:

  foreground = { ansi = 4 }
  

• 24-bit RGB color (tealdeer v1.5.0+)

  Example:

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

Section: [search]

This config section is used to configure the page search in the cache. The settings apply to tldr <page> and tldr --list.

languages

The list of languages that should be considered when searching. If unspecified, the list of languages will be inferred from the LANG and LANGUAGE environment variables. Either way, the language used can be overwritten using the --language command line flag.

[search]
# Show pages in German if available, otherwise show in English
languages = ["de", "en"]

platforms

The list of platforms that should be considered when searching. In addition to the platforms listed in the help text of the --platform flag, there are two special platforms available:

• "current": equals the platform that tealdeer was compiled for
• "all": adds all remaining platforms to the list

Tealdeer searches the platforms in order of appearance in this list. The default list of platforms is ["current", "common", "all"]. The list of platforms can be overwritten using the --platform command line flag.

[search]
# Search for linux and common, and then search windows before trying the remaining platforms
platforms = ["linux", "common", "windows", "all"]

Section: [updates]

This config section contains settings related to updating the tealdeer cache.

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.

auto_update

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

[updates]
auto_update = true

auto_update_interval_hours

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.

[updates]
auto_update = true
auto_update_interval_hours = 24

Download configuration

download_languages

The list of languages which should be downloaded when updating. If unspecified, the languages listed in the search.languages setting are used. Thus, this setting is the most useful to instruct tealdeer to download pages in additional languages that are not searched by default. Either way, the language used can be overwritten using the --language command line flag.

[search]
languages = ["de", "en"]

[updates]
# sometimes I like to read the Italian description
download_languages = ["de", "en", "it"]

archive_source

URL for the location of the tldr pages archive. By default the pages are fetched from the latest tldr-pages/tldr GitHub release.

[updates]
archive_source = "https://my-company.example.com/tldr/"

tls_backend

Specifies which TLS backend to use. Try changing this setting if you encounter certificate errors.

Available options:

• rustls-with-native-roots - Rustls (a TLS library in Rust) with native roots
• rustls-with-webpki-roots - Rustls with WebPKI roots
• native-tls - Native TLS
  • SChannel on Windows
  • Secure Transport on macOS
  • OpenSSL on other platforms

[updates]
tls_backend = "native-tls"

Section: [directories]

This section allows overriding some directory paths.

cache_dir

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.

[directories]
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.

custom_pages_dir

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.

[directories]
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"],
    capture_output=True,
    encoding="utf-8",
).stdout.splitlines()

for command in commands:
    output = subprocess.run(
        ["tldr", "--quiet", command],
        capture_output=True,
        encoding="utf-8",
    ).stdout
    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.