navi/README.md

navi

An interactive cheatsheet tool for the command-line and application launchers.

navi allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands. Suggested values for arguments are dinamically displayed in a list.

Pros

• it will make you type less
• it will spare you from knowing CLIs by heart
• it will teach you new one-liners

It uses fzf, skim, or Alfred under the hood and it can be either used as a command or as a shell widget (à la Ctrl-R).

Table of contents

• Installation
• Usage
• Cheatsheet repositories
• Cheatsheet syntax
• Customization
• Using it for shell scripting
• More info
• Trying out online
• Similar tools
• Etymology

Installation

navi can be installed with the following package managers:

The recommended way to install navi is by running:

brew install navi

If brew isn't available, you can check alternative install instructions.

Usage

There are 3 ways to use navi:

• by typing navi in the terminal and hitting <Enter>
• by invoking it via a shell widget in the terminal
  • this way, the shell history is correctly populated (e.g. docker run alpine instead of navi) and you can edit the command as you wish before executing it
• as an Alfred workflow

Cheatsheet repositories

Running navi for the first time will help you download and manage cheatsheets.

You can also:

• browse through featured cheatsheets
• import cheatsheets from git repositories
• write your own cheatsheets (and share them, if you want)
• use cheatsheets from other tools, such as tldr and cheat.sh

Cheatsheet syntax

Cheatsheets are described in .cheat files that look like this:

% git, code

# Change branch
git checkout <branch>

$ branch: git branch | awk '{print $NF}'

The full syntax and examples can be found here.

Customization

You can:

• change colors
• resize columns
• change how search is performed

Using it for shell scripting

Let's say you want to write a bash script that, among other things, asks the user to write the name of a git branch that should be checked out.

If you already have the cheatsheet above, then you write the following in your script:

navi --query "change branch" --best-match

If you want to set the <branch> beforehand in your script, you could then write:

branch="master" navi --query "change branch" --best-match

More info

Please run the following command to read more about all possible options:

navi --help

In addition, the /docs folder includes more information.

Trying out online

If you don't have access to a Unix shell at the moment and you want to live preview navi, head to this playground. It'll start a docker container with instructions for you to install and use the tool. Note: login required.

Similar tools

There are many similar projects out there (beavr, bro, cheat, cheat.sh, cmdmenu, eg, how2, howdoi and tldr, to name a few).

They are excellent projects, but navi remains unique in the following ways:

• it's natural to write cheatsheets tailored to your needs
• arguments are neither hardcoded nor a simple template

Etymology

In The Legend of Zelda Ocarina of Time, navi is a character that provides Link with a variety of clues to help him solve puzzles and progress in his quest.