Tealdeer

https://tealdeer-rs.github.io/tealdeer/
Admin
Tealdeer is a fast Rust implementation of tldr that provides simplified, example-based, and...
Tokens:6,486
Snippets:112
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example Tealdeer Configuration File (TOML)

Source: https://tealdeer-rs.github.io/tealdeer/config.html

An example TOML configuration file for Tealdeer. Customize display, style, and update settings.

```toml
[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

```

--------------------------------

### Example Custom Patch Path

Source: https://tealdeer-rs.github.io/tealdeer/usage_custom_pages.html

An example of a specific custom patch file path for the 'ufw' command.

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

--------------------------------

### Example Custom Page Path

Source: https://tealdeer-rs.github.io/tealdeer/usage_custom_pages.html

An example of a specific custom page file path for the 'ufw' command.

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

--------------------------------

### Install Shell Completions

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Copy completion scripts to the appropriate system directories for Bash, Fish, or Zsh.

```bash
cp completion/bash_tealdeer /usr/share/bash-completion/completions/tldr
```

```bash
cp completion/fish_tealdeer ~/.config/fish/completions/tldr.fish
```

```bash
cp completion/zsh_tealdeer /usr/share/zsh/site-functions/_tldr
```

--------------------------------

### Install Zsh Autocompletion for Tealdeer

Source: https://tealdeer-rs.github.io/tealdeer/installing.html

Copies the Zsh completion script to the site-functions directory for Zsh.

```bash
cp completion/zsh_tealdeer /usr/share/zsh/site-functions/_tldr
```

--------------------------------

### Install Fish Autocompletion for Tealdeer

Source: https://tealdeer-rs.github.io/tealdeer/installing.html

Copies the Fish shell completion script to the user's configuration directory.

```bash
cp completion/fish_tealdeer ~/.config/fish/completions/tldr.fish
```

--------------------------------

### Install Tealdeer via Cargo

Source: https://tealdeer-rs.github.io/tealdeer/installing.html

Use this command to build and install the tealdeer tool directly from its source using Cargo, Rust's package manager.

```bash
$ cargo install tealdeer
```

--------------------------------

### Install Bash Autocompletion for Tealdeer

Source: https://tealdeer-rs.github.io/tealdeer/installing.html

Copies the bash completion script to the appropriate directory for the Bash shell.

```bash
cp completion/bash_tealdeer /usr/share/bash-completion/completions/tldr
```

--------------------------------

### Append Custom Pages to Existing Commands

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Create a `<command>.patch.md` file to append custom examples to existing command pages. Place this file in the `$CUSTOM_PAGES_DIR`.

```bash
__
$CUSTOM_PAGES_DIR/<command>.patch.md
```

```bash
__
~/.local/share/tealdeer/pages/ufw.patch.md
```

--------------------------------

### Set Foreground Color to Green

Source: https://tealdeer-rs.github.io/tealdeer/config_style.html

Use this to set the foreground color of command examples to green. This uses a simple color string.

```toml
foreground = "green"
```

--------------------------------

### Seed Tealdeer Configuration File

Source: https://tealdeer-rs.github.io/tealdeer/config.html

Generates a default `config.toml` file in the appropriate location for your operating system. This is useful for starting your customization.

```bash
tldr --seed-config
```

--------------------------------

### Build Tealdeer from Source

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Compile the project from source with various feature flags.

```bash
$ cargo build --release
```

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

```bash
$ cargo build --features logging
```

--------------------------------

### Show Tealdeer Configuration Paths

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Use the `tldr --show-paths` command to display the locations where Tealdeer looks for configuration files and pages.

```bash
__
$ tldr --show-paths
```

--------------------------------

### View Tealdeer Help

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Display the command-line interface options and usage information.

```text
tealdeer 1.8.1: 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/.
```

--------------------------------

### Configure Custom Pages

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Define the path structure for custom command pages.

```bash
$CUSTOM_PAGES_DIR/<command>.page.md
```

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

--------------------------------

### Configure Compact Output

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Enable compact output by setting `compact` to `true` in the `[display]` section. This strips out empty lines from the output. The default is `false`.

```toml
__
[display]
compact = true

```

--------------------------------

### Configure Search Platforms

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Define the order of platforms to search for pages. Includes special values like 'current' and 'all'. The default is `["current", "common", "all"]`. Platform can be overridden with the `--platform` flag.

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

```

--------------------------------

### List all commands with summaries

Source: https://tealdeer-rs.github.io/tealdeer/tips_and_tricks.html

A Python script that iterates through all available tldr pages to extract and print the first-line summary for each command.

```python
#!/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}")
```

--------------------------------

### Configure Show Title

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Display the command name at the top of the output by setting `show_title` to `true` in the `[display]` section. This uses the `command_name` style configuration. The default is `false`.

```toml
__
[display]
show_title = true

```

--------------------------------

### Show Tealdeer Custom Pages Path

Source: https://tealdeer-rs.github.io/tealdeer/usage_custom_pages.html

Run this command to display the directory where Tealdeer looks for custom pages on your system.

```bash
tldr --show-paths
```

--------------------------------

### Configure TLS Backend

Source: https://tealdeer-rs.github.io/tealdeer/config_updates.html

Sets the TLS library used for network requests. Useful for troubleshooting certificate errors.

```toml
[updates]
tls_backend = "native-tls"
```

--------------------------------

### Tealdeer CLI Usage

Source: https://tealdeer-rs.github.io/tealdeer/usage.html

This section details the primary command and its available options for interacting with Tealdeer.

```APIDOC
## Tealdeer CLI Usage

### Description
Tealdeer is a command-line tool for accessing TLDR pages. It is invoked using the `tldr` binary.

### Method
N/A (Command-line tool)

### Endpoint
N/A (Command-line tool)

### Parameters
#### Command
- **COMMAND** (string) - Required - The command to show (e.g., `tar` or `git log`). Multiple commands can be specified.

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

### Request Example
```bash
tldr tar
tldr -p linux git log
```

### Response
Output depends on the command and options used. Typically, rendered TLDR pages or informational messages.

#### Success Response (200)
- **Output** (string) - The rendered TLDR page content or informational message.

#### Response Example
```
# tar

# Extract files from an archive

Extract files from a tar archive (often compressed with gzip or bzip2).

- Extract all files from archive.tar to the current directory:
  tar -xf archive.tar

- Extract all files from archive.tar.gz to the current directory:
  tar -xzf archive.tar.gz

- Extract all files from archive.tar.bz2 to the current directory:
  tar -xjf archive.tar.bz2

- Create an archive:
  tar -cf archive.tar files/...

- Create a gzipped archive:
  tar -czf archive.tar.gz files/...

- Create a bzip2 archive:
  tar -cjf archive.tar.bz2 files/...
```
```

--------------------------------

### Build Tealdeer with Native TLS Support

Source: https://tealdeer-rs.github.io/tealdeer/installing.html

Build tealdeer in release mode, enabling native TLS support for secure network communication. This is useful for environments where native TLS libraries are preferred or required.

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

--------------------------------

### Configure search platforms

Source: https://tealdeer-rs.github.io/tealdeer/config_search.html

Specifies the order of platforms to search. Supports special values 'current' and 'all'.

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

--------------------------------

### Build Tealdeer in Release Mode

Source: https://tealdeer-rs.github.io/tealdeer/installing.html

Compile tealdeer with optimizations for production use. This command generates a release build.

```bash
$ cargo build --release
```

--------------------------------

### Configure Directory Paths

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Overrides default paths for the cache and custom pages directories using absolute paths.

```toml
[directories]
cache_dir = "/home/myuser/.tealdeer-cache/"
```

```toml
[directories]
custom_pages_dir = "/home/myuser/custom-tldr-pages/"
```

--------------------------------

### Set Custom Archive Source

Source: https://tealdeer-rs.github.io/tealdeer/config_updates.html

Overrides the default GitHub release URL for fetching tldr pages.

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

--------------------------------

### Display a random tldr page

Source: https://tealdeer-rs.github.io/tealdeer/tips_and_tricks.html

Uses shuf to select a random command from the tldr list and displays its documentation.

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

--------------------------------

### Configure Style Background RGB Color

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Set the background color using a 24-bit RGB value. Requires tealdeer v1.5.0 or later.

```toml
__
background = { rgb = { r = 255, g = 255, b = 255 } }

```

--------------------------------

### Configure Auto-Update Settings

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Enables the auto-update feature and sets the refresh interval in hours.

```toml
[updates]
auto_update = true
```

```toml
[updates]
auto_update = true
auto_update_interval_hours = 24
```

--------------------------------

### Configure Display Pager

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Enable the use of a pager (like `less -R`) for command output by setting `use_pager` to `true` in the `[display]` section. This is disabled by default.

```toml
__
[display]
use_pager = true

```

--------------------------------

### Build Tealdeer in Debug Mode with Logging

Source: https://tealdeer-rs.github.io/tealdeer/installing.html

Compile tealdeer with debugging symbols and enable logging support. This build is suitable for development and troubleshooting. To enable logging at runtime, export the RUST_LOG=tldr=debug environment variable.

```bash
$ cargo build --features logging
```

--------------------------------

### Custom Page Path Structure

Source: https://tealdeer-rs.github.io/tealdeer/usage_custom_pages.html

This is the general path structure for creating a custom page that overrides an existing tldr page.

```bash
$CUSTOM_PAGES_DIR/<command>.page.md
```

--------------------------------

### Custom Patch Path Structure

Source: https://tealdeer-rs.github.io/tealdeer/usage_custom_pages.html

This is the general path structure for creating a custom patch file to extend an existing tldr page.

```bash
$CUSTOM_PAGES_DIR/<command>.patch.md
```

--------------------------------

### Set Background Color with RGB

Source: https://tealdeer-rs.github.io/tealdeer/config_style.html

Use this to set the background color using a 24-bit RGB value. Requires tealdeer v1.5.0 or later.

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

--------------------------------

### Enable Compact Output in Tealdeer

Source: https://tealdeer-rs.github.io/tealdeer/config_display.html

Set `compact` to `true` to strip out empty lines from the command output for a more compact view.

```toml
[display]
compact = true

```

--------------------------------

### Configure Search Languages

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Specify the preferred order of languages for searching pages. If not specified, languages are inferred from environment variables. The language can be overridden with the `--language` flag.

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

```

--------------------------------

### Configure search languages

Source: https://tealdeer-rs.github.io/tealdeer/config_search.html

Defines the order of languages to search for tldr pages. Overrides environment variables.

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

--------------------------------

### Override cache directory in config

Source: https://tealdeer-rs.github.io/tealdeer/config_directories.html

Specify an absolute path for the cache directory. The directory will be created automatically if it does not exist.

```toml
[directories]
cache_dir = "/home/myuser/.tealdeer-cache/"
```

--------------------------------

### Enable Pager in Tealdeer

Source: https://tealdeer-rs.github.io/tealdeer/config_display.html

Set `use_pager` to `true` to enable the pager for command output. This uses `less -R` by default. Not available on Windows.

```toml
[display]
use_pager = true

```

--------------------------------

### Configure Download Languages

Source: https://tealdeer-rs.github.io/tealdeer/config_updates.html

Specifies additional languages to download for tldr pages beyond the default search languages.

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

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

--------------------------------

### Set Foreground Color with ANSI Code

Source: https://tealdeer-rs.github.io/tealdeer/config_style.html

Use this to set the foreground color using a 256-color ANSI code. Requires tealdeer v1.5.0 or later.

```toml
foreground = { ansi = 4 }
```

--------------------------------

### Configure Style Foreground ANSI Color

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Set the foreground color using a 256-color ANSI code. Requires tealdeer v1.5.0 or later.

```toml
__
foreground = { ansi = 4 }

```

--------------------------------

### Override custom pages directory in config

Source: https://tealdeer-rs.github.io/tealdeer/config_directories.html

Define an absolute path for the directory containing custom tldr pages.

```toml
[directories]
custom_pages_dir = "/home/myuser/custom-tldr-pages/"
```

--------------------------------

### Enable Automatic Updates

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Configure Tealdeer to automatically refresh the cache when it's outdated by setting `auto_update` to `true` in the `[updates]` section. This is disabled by default.

```toml
__
[updates]
auto_update = true

```

--------------------------------

### Enable Automatic Cache Updates

Source: https://tealdeer-rs.github.io/tealdeer/config_updates.html

Configures Tealdeer to automatically refresh the cache when outdated.

```toml
[updates]
auto_update = true
```

--------------------------------

### Show Command Title in Tealdeer

Source: https://tealdeer-rs.github.io/tealdeer/config_display.html

Set `show_title` to `true` to display the command name at the top of the output. The name is styled using the `command_name` style configuration.

```toml
[display]
show_title = true

```

--------------------------------

### Configure Style Foreground Color

Source: https://tealdeer-rs.github.io/tealdeer/print.html

Set the foreground color for a style element using a color string like 'green'. Other options include ANSI codes and RGB values.

```toml
__
foreground = "green"

```

--------------------------------

### Set Auto-Update Interval

Source: https://tealdeer-rs.github.io/tealdeer/config_updates.html

Defines the frequency in hours for automatic cache updates. Requires auto_update to be enabled.

```toml
[updates]
auto_update = true
auto_update_interval_hours = 24
```
Tokens:
Raw