A very fast implementation of tldr in Rust: Simplified, example based and community-driven man pages.
If you pronounce "tldr" in English, it sounds somewhat like "tealdeer". Hence the project name :)
In case you're in a hurry and just want to quickly try tealdeer, you can find static binaries on the GitHub releases page!
High level project goals:
- Download and cache pages
- Don't require a network connection for anything besides updating the cache
- Command line interface similar or equivalent to the NodeJS client
- Be fast
A tool like
tldr should be as frictionless as possible to use. It should be
easy to invoke (just
tldr tar, not using another subcommand like
tldr find tar) and it should show the output as fast as possible.
tealdeer reaches these goals. During a (highly non-scientific) test (see
#38 for details), I tested the
invocation speed of
tldr <command> for a few of the existing clients:
|Client||Times (ms)||Avg of 5 (ms)|
|Go client by k3mist||
tealdeer was the winner here, although the C client and the Bash client are in the same speed class. Interpreted languages are clearly much slower to invoke, a delay of 170 milliseconds is definitely noticeable and increases friction for the user.
tldr [options] <command> tldr [options] Options: -h --help Show this screen -v --version Show version information -l --list List all commands in the cache -f --render <file> Render a specific markdown file -o --os <type> Override the operating system [linux, osx, sunos] -u --update Update the local cache -c --clear-cache Clear the local cache -q --quiet Suppress informational messages --config-path Show config file path --seed-config Create a basic config Examples: $ tldr tar $ tldr --list To control the cache: $ tldr --update $ tldr --clear-cache To render a local file (for testing): $ tldr --render /path/to/file.md
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!
Builds for other platforms are planned.
Cargo Install (any platform)
Build and install the tool via cargo...
$ cargo install tealdeer
From Package Manager
tealdeer has been added to a few package managers:
- Arch Linux AUR:
- macOS Homebrew:
- Void Linux XBPS:
From Source (any platform)
tealdeer requires at least Rust 1.31.
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
The tldr command can be customized with a config file called
Creating the config file can be done manually or with the help of tldr:
$ tldr --seed-config
The configuration file path follows OS conventions. It can be queried with the following command:
$ tldr --config-path
Using the config file, the style (e.g. colors or underlines) can be customized.
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
example_variable: The variables in the example
Currently supported attributes:
foreground(color string, see below)
background(color string, see below)
The currently supported colors are:
- Bash: copy
- Fish: copy
To run tests:
$ cargo test
To run lints:
$ rustup component add clippy $ cargo clean && cargo clippy
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Thanks to @SShrike for coming up with the name "tealdeer"!