When you first start learning things, it’s always a struggle to get to a point where you are comfortable with the topic. And, it’s no different for Engineers trying to learn the Linux command line. Luckily, there’s a help utility baked right into most distributions of Linux. That utility is called man pages. Man pages is short for manual pages, and these are included with software packages as part of the help documentation for any given application. On a side note, they’re typically stored in the “/usr/share/man” directory. Often shorted to just “man,” these pages are packed full of helpful information on how to use the command with which you’re working. Almost all of these pages are well written, but they are nonetheless hard to read and understand for most new Engineers and even some seasoned Engineers. They are written in such a way, they almost assume a certain level of understanding about command line usage and syntax, with their esoteric ways of describing how to use a utility.
One of the best things about GNU/Linux and the plethora of GNU tools is their open-source foundation. That means that if someone thinks of a better way of doing something, they can build it, put it out into the world, and let people tinker with it. One of those “better ways” I recently discovered is a little utility called tldr pages. In common vernacular, tldr stands for “too long; didn’t read,” and the same goes here. The authors of the utility describe tldr pages in this way: “The tldr pages are a community effort to simplify the beloved man pages with practical examples.”
Getting started with tldr pages is simple. Startup your favorite web browser of choice and point it towards tldr.sh or tldr.ostera.io. Once you arrive at the latter site, you will see a quick description of the page and its purpose. You will also notice a search box at the top of the page near the logo. All you have to do is start typing in the name of the command you want some help with, and it will begin to appear. There is also the same search box on tldr.sh, but it is further down. What makes tldr pages different from man pages is the manner in which the information is presented. Instead of using hard-to-understand syntax, explanations of arguments, and examples–if you’re lucky–you are presented with brief examples of how to use the command for different scenarios. In my estimation, this is far easier to understand and quicker to deliver you the results for which you’re looking!
But, what good is a command line utility if you can’t access it from the command line?! Well, we are in luck! We can install tldr pages and use it in our daily command line usage. Now, this installation is a little more advanced than some of my previous articles, but don’t let that scare you. We will simply have to install Node.js to use tldr pages on Ubuntu or other distros that use the Advanced Package Tool (APT). So, let’s install Node.js.
$ sudo apt install nodejs npm
After that, we can install tldr pages.
$ sudo npm install -g tldr
Once it is installed, you will want to update it first.
$ tldr --update
And now you’re off to the races! Try running the following command to test everything works.
$ tldr tldr
You should see the following output:
tldr
Displays simple help pages for command-line tools, from the tldr-pages project.
More information: https://tldr.sh.
- Show the tldr page for a command (hint: this is how you got here!):
tldr command
- Show the tldr page for cd, overriding the default platform:
tldr -p android|linux|osx|sunos|windows cd
- Show the tldr page for a subcommand:
tldr git-checkout
- Update local pages (if the client supports caching):
tldr -u
See also: cd
It should be mentioned that there are other Portable Operating System Interface (POSIX) compatible shell clients for Debian and distros. You can find them across the Internet and on GitHub. Here is a popular one that I have used on my Mac: POSIX tldr by Ray Lee
In the end, this is not a replacement for man pages, but it is a great addition. It’s easy to use on the web or in the command line and won’t let you down when you just need a quick reminder on how to use grep for the millionth time.
