Interactive Cheat Sheet

What exactly was that parameter for creating an archive with tar? Command-line aficionados know that if nothing shows up with the Bash history command, your only option is to look at the manpage. While manpages are generally useful, some are so extensive that the time spent searching for information is disproportionate to the task at hand. An alternative to this problem is an interactive cheat sheet.

While there are plenty of cheat sheet tools on GitHub, the relatively young navi [1] offers both good functionality and an eye-pleasing design. Navi helps users browse built-in (DIY or downloaded) cheat sheets to display options and arguments for commands or directly execute the commands. Navi (as well as similar tools) lets you interactively learn about newly discovered commands and explore all their possibilities.

Installation

You can quickly install navi from the website (Listing 1). In addition, you can optionally install navi in an arbitrary directory (line 6) instead of in your path.

01 $ sudo git clone --depth 1 https://github.com/denisidoro/navi /opt/navi
02 $ cd /opt/navi
03 ### Install in $PATH
04 $ sudo make install
05 ### Alternatively
06 $ ./scripts/install <directory>

Navi does have a couple of dependencies. To avoid having navi complain, you must install the fzf string matching algorithm, a search tool that uses fuzzy searches to quickly find specific strings in a longer string or text.

You can find fzf in the Debian, Fedora, and Arch Linux repositories, where you can install it with the standard package manager. Alternatively, Mac OS X users can use Homebrew [2] for the installation. For Z shell [3] users, navi's developer offers a guide for integrating the widely used Oh My ZSH [4] configuration file.

Navi's only other dependency is ncurses, which should be preinstalled on every distribution.

Since work on the relatively young navi is ongoing, you will want to update the software regularly. When a new version appears on GitHub, you can update navi quickly with git (Listing 2).

$ cd "$(navi home)"
$ sudo git pull

Getting Started

First, you will want to briefly familiarize yourself with navi's arguments and options by calling navi --help in a shell. Then start the program by entering navi. Navi opens a current list of 242 embedded cheat sheets (Figure 1).

Figure 1: Navi displays the current list of cheat sheets at startup.

In the three-part view in Figure 1, you can see the application or environment from which the commands originate on the left, the tasks to be performed with them in the middle, and the corresponding command on the right. You can choose to limit the display of commands to one category. For example,

navi query git

only shows commands for git. Alternatively, you can narrow down the results in the window by typing ip addr, which results in the three commands that deal with IP addresses (Figure 2).

Figure 2: Keywords are used to limit the commands to a specific topic directly in the window.

Direct Execution

Navi's interactivity comes into play when you double-click on a selected command. If the command requires no further input, the program passes it directly to the shell. For instance, clicking on the List running services task from the systemctl, service category takes you directly to a list of running services (Figure 3). In this example, direct execution of the command does not pose a problem, because the command only prints a list and makes no other changes to your system.

Figure 3: Commands that do not change the system (e.g., listing active services) can be executed directly without any risk.

Hitting Pause

What if you are not sure that you've chosen the correct command? For instances where the command will change your system, you can add the --print option to the command to prevent it from executing directly. If you want to use this option as a default, define a corresponding alias, such as

alias navi='navi --print'

and add it in your ~/.bashrc.

You also might want to use the --print option for commands that require further input before execution. For example, the Create a tar containing files task from the compression section requires two pieces of input from the user; the software prompts you for them when you click on the command. For name:, enter the desired name of the tar archive, while files: expects the path to the files you want to compress.

Once you have confirmed both entries, the tool will display the command that creates the corresponding archive (Figure 4). If you have used the --print option, navi will not execute this command, giving you the opportunity to determine if the command has the desired effect. If the command does what you expect, then copy the command and run it.

Figure 4: The command shown here for creating a tarball requires the user to enter a name and a path before the tool shows the command.

Online Cheat Sheets

Another way to use navi is to enter a command directly as an argument at launch time. For example, entering

navi search apt

will return eight commands for Debian's apt package tool. These commands do not originate from the installed navi package; instead, they come from online sources, such as cheat.sh [5], which offers additional cheat sheets (Figure 5).

Figure 5: You can use navi to integrate commands from online cheat sheets. However, you should investigate this type of command more thoroughly with --print before you take the plunge.

Integrating the Widget

You can also add navi to the shell as a widget, which helps keep the history up to date and lets you edit the command to suit your needs before running it.

To use the software as a widget, add the following line

source "$(navi widget bash)"

to your ~/.bashrc or /etc/bash.bashrc file. This lets you launch navi by pressing Ctrl+G in the future. If the keyboard shortcut is already assigned on your system, or if you want to assign a different shortcut, you can define it in /opt/navi/navi.plugin.bash.

DIY

If you are missing an important command, you can create your own cheat sheet for the command and call it in navi. Use a file from /opt/navi/cheats/ as a template (for a detailed explanation of the syntax, see GitHub [6]). Then call the new cheat sheet with a command like the one shown in line 1 of Listing 3 or include several directories in $NAVI_PATH, separated by colons (line 2).

01 $ navi --path "/<MyOwn>/<Cheatsheets>"
02 $ export NAVI_PATH="/<MyOwn>/<Cheatsheets>:/<Even>/<more>/<Cheatsheets>"

Conclusions

While the built-in cheat sheets for Docker, Kubernetes, and Git focus strongly on developers' needs, they also contain many cheat sheets useful for desktop users. In particular, navi makes it easier for console gamers to handle complex command-line commands.

In addition, navi can be extended by integrating online or DIY cheat sheets. However, navi's developer recommends using the --print option to check commands from online cheat sheets.

Finally, Katacoda [7] lets you test navi prior to installation to see if it's a good fit for your needs. If it isn't, you will find other similar tools on GitHub, such as cheat, cmdmenu, BEAVR, and howdoi.