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

(Note: You might need to install OpenSSL development headers, otherwise you get a "failed to run custom build command for openssl-sys" error message. The package is called libssl-dev on Ubuntu.)

Build From Source

Debug build with logging enabled:

$ cargo build --features logging

Release build without logging:

$ cargo build --release

To enable the log output, set the RUST_LOG env variable:

$ export RUST_LOG=tldr=debug

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 <PLATFORM>    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, 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 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

Example:

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

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.

Path:

$CUSTOM_PAGES_DIR/<command>.patch

Example:

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

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.

Override Cache Directory

Similarly, the cache directory where the pages are downloaded to, also follows OS conventions. On Linux, it will usually be at ~/.cache/tealdeer/. The path can be overwritten using the environment variable TEALDEER_CACHE_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/"