A companion command to the traditional man

Get the summary of popular Unix / Linux commands

Photo by Gabriel Heinzer on Unsplash

I don’t know if I am the only one but I often forget how to use regular commands like rsync or scp, and trying to read the man command is a pain in the ass. I have always wanted to have a simple summary explaining the most common uses of a command, and recently I found the project tldr.

Installation

To install tldr on Mac OS, you can use homebrew:

$ brew install tldr

For the other systems you will need NodeJS or python installed on your machine to use their default client to install it.

# for NodeJS users
$ npm install -g tldr

# for python users
$ pip install tldr

Although for python users, I will recommend you use the project pipx to have your command available globally:

$ pipx install tldr

Usage

It is pretty straightforward, you just need to replace man by tldr and you are done. For example, to get a summary of scp usage I will type:

$ tldr scp

  scp

  Secure copy.
  Copy files between hosts using Secure Copy Protocol over SSH.
  More information: https://man.openbsd.org/scp.

  - Copy a local file to a remote host:
    scp path/to/local_file remote_host:path/to/remote_file

  - Use a specific port when connecting to the remote host:
    scp -P port path/to/local_file remote_host:path/to/remote_file

  - Copy a file from a remote host to a local directory:
    scp remote_host:path/to/remote_file path/to/local_directory

  - Recursively copy the contents of a directory from a remote host to a local directory:
    scp -r remote_host:path/to/remote_directory path/to/local_directory

  - Copy a file between two remote hosts transferring through the local host:
    scp -3 host1:path/to/remote_file host2:path/to/remote_directory

  - Use a specific username when connecting to the remote host:
    scp path/to/local_file remote_username@remote_host:path/to/remote_directory

  - Use a specific ssh private key for authentication with the remote host:
    scp -i ~/.ssh/private_key local_file remote_host:/path/remote_file

Easy peasy! Now I have concrete examples of scp that I can read!

Note that tldr is available in many languages. By default, it will use the language defined on your operating system and if it can’t find one, it will use English. For example, on my computer, the French language is the default one, but scp summary doesn’t have a translation in French yet, this is why I get the English summary. 😆

But, if I display the summary of the tmux command which has a French summary I get this:

$ tldr tmux

  tmux

  Multiplexeur de terminaux. Permet plusieurs sessions avec fenêtres, panneaux, et plus encore.
  Plus d'informations : https://github.com/tmux/tmux.

  - Démarrer une nouvelle session :
    tmux

  - Démarrer une nouvelle session nommée :
    tmux new-session -s nom

  - Lister les sessions existantes :
    tmux ls

  - S'attacher à la session utilisée la plus récemment :
    tmux attach-session

  - S'attacher à une session nommée :
    tmux attach-session -t nom

  - Se détacher de la session actuelle (avec le préfixe Ctrl-B) :
    Ctrl-B d

  - Détruire une session nommée :
    tmux kill-session -t nom

  - Détruire la session actuelle (avec le préfixe Ctrl-B) :
    Ctrl-B :kill-session<Enter>

You can also try to force the language with the -L option. You need to pass it the representation of the language with two letters, for example, en, fr, etc… To know all the available languages, you need to look at the homepage, and especially all the folders pages.XX.

Also, if you don’t like the colors used to display the summary, you can configure yours. For the python client, you can configure the following environment variables:

export TLDR_COLOR_NAME="cyan"
export TLDR_COLOR_DESCRIPTION="white"
export TLDR_COLOR_EXAMPLE="green"
export TLDR_COLOR_COMMAND="red"
export TLDR_COLOR_PARAMETER="white"

You can save those in the .bashrc file for example if you use the bash shell. This will avoid you to use type them for each session.

There are others parameters you can configure, you can look at the documentation of the client if you want to know more. For the other clients, you can also customize them, for the NodeJS client, you can look at the documentation here, and for the Mac OS client, you can look at the documentation here.

Bonus: there is an online cheatsheet doing the same job as tldr, I described it in this article.

This is all for this article, hope you enjoyed it. Take care of yourself and see you next time! 😁