Tealdeer: Introduction

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

Screenshot

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

Installing

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:

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 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.)

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.6.1
Danilo Bargen <mail@dbrgn.ch>, Niklas Mohrin <dev@niklasmohrin.de>
A fast TLDR client

USAGE:
    tldr [OPTIONS] [COMMAND]...

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

OPTIONS:
    -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, freebsd, netbsd, openbsd]
    -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,
                                  never]
    -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.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, updates or directories).

[display]
compact = false
use_pager = true

[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

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: [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.

`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

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.

Tealdeer User Manual

Tealdeer: Introduction

Links

Installing

Package Managers

Static Binaries (Linux)

Through `cargo install`

Build From Source

Autocompletion

Usage

Custom Pages and Patches

Custom Pages

Custom Patches

Configuration

Configfile Path

Config Example

Override Config Directory

Section: [display]

`use_pager`

`compact`

Section: [style]

Style Targets

Attributes

Section: [updates]

Automatic updates

`auto_update`

`auto_update_interval_hours`

Section: [directories]

`cache_dir`

`custom_pages_dir`

Tips and Tricks

Showing a random page on shell start

Displaying all pages with their summary

Extending this chapter