navi Documentation

An interactive cheatsheet tool for the command-line

17,110 stars Rust Rust 1 file · ~6,250 tokens #bash#cheatsheets#cli#command-line#rust#shell#snippet#snippets
RAW Doc

File: README.md

An interactive cheatsheet tool for the command-line.

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

Pros

  • it will spare you from knowing CLIs by heart
  • it will spare you from copy-pasting output from intermediate commands
  • it will make you type less
  • it will teach you new one-liners

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

Table of contents

Installation

The recommended way to install navi is by running:

sh
brew install navi

[!NOTE]
For more details on how to install Navi, see docs/installation

navi can be installed with the following package managers:

Usage

There are multiple ways to use navi:

  • by typing navi in the terminal
    • pros: you have access to all possible subcommands and flags
  • as a shell widget for the terminal
    • pros: the shell history is correctly populated (i.e. with the actual command you ran instead of navi) and you can edit the command as you wish before executing it
  • as a Tmux widget
    • pros: you can use your cheatsheets in any command-line app even in SSH sessions
  • as aliases
  • as a shell scripting tool

In particular, check these instructions if you want to replicate what's shown in the demo above.

Cheatsheet repositories

Running navi for the first time will help you download and manage cheatsheets. By default, they are stored at ~/.local/share/navi/cheats/.

You can also:

Cheatsheet syntax

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

sh
% git, code

# Change branch
git checkout 

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

The full syntax and examples can be found here.

Customization

You can:

More info

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

sh
navi --help

In addition, please check the /docs folder or the website.

File: docs/installation/README.md

Installation of navi

This is a reference of all known methods to install navi.

[!CAUTION]
Navi, as of now, has only two official builds, the released binaries on GitHub
and the published package on brew.

All the other packages are community-maintained.

Using package managers

Homebrew

sh
brew install navi

[!NOTE]
See brew.sh for more details.

Using Gentoo

[!WARNING]
You need to enable the GURU overlay for the instructions below to work correctly.

For more details see:

sh
emerge -a app-misc/navi

[!NOTE]
See Gentoo.org for more details.

Using Pacman

sh
pacman -S navi

[!NOTE]
See wiki.archlinux.org/title/Pacman for more details.

Using nix

sh
nix-env -iA nixpkgs.navi

[!NOTE]
See nixos.org for more details

Using Cargo

bash
cargo install --locked navi

[!NOTE]
See @rust-lang/cargo for more details.

Using Chocolatey

bash
choco install navi

[!CAUTION]
You currently need to create the config file $env:USERPROFILE\AppData\Roaming\navi\config.yaml
and define the shell.command directive as powershell for navi to work correctly.

yaml
shell:
  command: powershell

[!NOTE]
See community.chocolatey.org for more details.

Using the installation script

Navi has an installation script ready for you to use, you can call it like this:

bash
bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)

If you need to define the directory for the binary, you can call it like this:

bash
BIN_DIR=/usr/local/bin bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)

Downloading pre-compiled binaries

With each release, we try our best to build and publish a binary for each
supported platform, you can find them here:
@denisidoro/navi/releases/latest

What you need to do is:

  • to download the binary corresponding to the version you want to install
  • to extract the content of the archive to your $PATH

Building from source

You can also build navi from source, it's mainly used by contributors to
test their modifications but can be used by end users who want to build their own version.

  • You need to clone the repository:

    bash
    git clone https://github.com/denisidoro/navi && cd navi

  • Call make

    bash
    make install

You can specify the binary directory with:

bash
make BIN_DIR=/usr/local/bin install

Compile time environment variables

navi supports environment variables at compile time that will modify the behavior of navi at runtime, they are:

Environment variable Description
NAVI_PATH This defines the default path used by navi for cheatsheets.
NAVI_CONFIG This defines the default configuration file used by navi.

Other package managers

You can find navi for more package managers by clicking on the image below:

Feel free to be the maintainer of navi for any package manager you'd like!

File: docs/deprecated/Alfred/README.md

Alfred

[!CAUTION]
This feature has been deprecated and support has been dropped since 2.16.0.

The latest version with support is 2.15.1.

This is experimental. If you face any issues, please report here.

Instructions

File: docs/contributions/documentation/README.md

Contribute documentation to Navi

If you don't want or can't code in Rust, we welcome all contributions,
even more so if it's related to documentation.

The documentation of Navi is currently made in Markdown.

Markdown documentation

The documentation source files are located in the docs/ folder and are mainly grouped by features.
The current documentation follows a structure where one folder equals one topic.

Here is a quick representation of the folder structure this documentation currently follows:

txt
.
+-- docs
|   +-- examples
|   |   +-- <topic-examples>
|   +-- src
|   |   +-- <topic-source-files>
|   |   |   +-- <sorted-by-type>
|   +-- <topic>
|   |   +-- README.md

You can see that we have separated the src and examples folder from the topic with the intent to make it
easier to find each type of documentation.

[!NOTE]
It is recommended to not go deeper than 3 levels in the documentation.

File: docs/contributions/code/README.md

Contribute code to Navi

Navi is written in Rust, the widgets may be written in any language given it can be integrated with Navi.

If you take the example of the most common widgets for Navi they are written in their shell scripting language
because they intend to integrate Navi with the shell in question (Fish, Zsh, NuShell, PowerShell, etc.).

We separate Navi into two categories:

  • Navi Core which refers to Navi's code in Rust
  • Navi Widgets which refers to code that intends to integrate Navi with a 3rd-party software

Contribute to Navi Core

If you want to contribute to Navi Core there are certain steps you need to follow for
your changes to be accepted.

  1. First, open an issue if no opened issues are related to the change you want to contribute.

  2. [Optional] Wait to have an opinion from the maintainers, developers or contributors from Navi.

    This step is marked as Optional as you can open a Merge Request (MR)/Pull Request (PR)
    without having to open an issue beforehand, although it is recommended to not do so.

    We ask you to wait before working on a PR as the way you see a feature and its implementation
    might not be similar on how a maintainer of Navi sees it.

    This will save you and the maintainers time.

  3. Fork the repository and iterate over your changes.

  4. Update Navi documentation

    If you implement a new feature, you will need to create a new entry in the project's
    documentation for users to know what has changed.

    No significant modification in Navi's behaviour should be merged without being documented.
    For more details I recommend you to see contributions/documentation/.

  5. Open a PR on denisidoro/navi and request a review

  6. [Optional] Your PR needs revisions and changes before it can be merged

    It's not rare that your PR will need changes before it can be accepted by the maintainers
    and then merged into the main branch.

  7. Your PR has been merged

    Congratulations! Your PR has been reviewed and merged, you should be proud of it,
    and we thank you for your contribution.

    The next release cycle will package all contributions into a new release and users
    throughout the world will be able to use your new feature(s).

File: docs/contributions/bugs/README.md

Contribute in opening bug tickets

Like any other software, navi has bugs.

If you encounter an issue with Navi, we encourage you to open a bug ticket.
Please see Bug report template then proceed to Issues tab to open an issue.

File: docs/contributions/README.md

This section is about the ways you can contribute to Navi and its ecosystem.

How to contribute to Navi

You have multiple ways to contribute to navi, here are the documented ones:

Please see each section for more details.

Versioning Scheme

Type Description
Major Anything which introduces a major breaking change. The bash to rust rewrite was such an example.
Minor Almost everything.
Fix A fix, just like its name. It should be micro releases with minimal changes.

Deprecation of features

Once you introduce a feature, you need to have a clear view of when we're
going to remove its support within navi.

In order to offer stability to the users, we prefer having 10 minor versions
between the deprecation notice and the removal of its support.

txt
Version where the feature is being deprecated: 0.10.0
Version where the support is dropped: 0.20.0

[!NOTE]
This rule is not absolute and each feature deprecation needs to be handled
carefully given its own circumstances, but try to stick as close as possible
to this rule.

File: docs/configuration/README.md

Configuring Navi

Navi allows you to configure it with a YAML configuration.

Paths and Environment Variables

On the technical side, navi uses the directories-next crate for rust,
which defines platform-specific locations to store the configuration files,
the cache and other types of files an application might need.

[!TIP]
For example, this is why cheatsheets are being stored in ~/Library/Application Support/navi on macOS.

[!NOTE]
Interested on how directories-next works?
Go see their crates.io page: crates.io/crates/directories-next

The default configuration file path

During the compilation of navi, the default configuration file path is set by the $NAVI_CONFIG environment variable.
If it is not set, it fallbacks to ~/.config/navi/config.yaml.

You can check your default configuration file path with the info subcommand,
see /docs/usage/commands/info/ for more details.

Cheatsheets paths

Navi checks the paths in the following order until it finds a value:

  1. the $NAVI_PATH environment variable
  2. the configuration file
  3. The default value of navi

The default cheatsheets path

By default, navi stores the cheatsheets in the ~/.local/share/navi/cheats/ directory.

You can check your default cheatsheets path with the info subcommand,
see /docs/usage/commands/info/ for more details.

Defining the cheatsheets path with the environment variable

The cheatsheets path can be defined using the $NAVI_PATH environment variable in a colon-separated list, for example:

sh
export NAVI_PATH='/path/to/a/dir:/path/to/another/dir:/yet/another/dir'

Defining the cheatsheets path in the configuration file

You can define the cheatsheets path in the configuration file with the following syntax:

yaml
cheats:
  paths:
    - /path/to/some/dir # on unix-like os
    - F:\\path\\to\\dir # on Windows

[DEPRECATED] - Using the `path` directive

Until 2.17.0, you could define your cheatsheets path with the path directive with the following syntax:

yaml
cheats:
  path: /path/to/some/dir

The directive is now deprecated and will be removed in 2.27.0.

Customization

Changing colors

fzf color scheme

You can change the color scheme of fzf by overriding fzf options.

[!NOTE]
See @junegunn/fzf/wiki/Color-schemes and
#overriding-fzf-options for more details.

You can change the text color for each column of navi in the configuration file with the following syntax:

yaml
style:
  tag:
    color: <your color for tags>
  comment:
    color: <your color for comments>
  snippet:
    color: <your color for snippets>

Below is an example of what to do if you'd like navi to look like the French flag:

  • config.yaml:

    yaml
    style:
  tag:
    color: blue
  comment:
    color: white
  snippet:
    color: red

  • The result:

Resizing columns

You can change the column width of each column of navi in the configuration file with the following syntax:

yaml
style:
  tag:
    width_percentage: <width relative to the terminal window>
    min_width: <width as number of characters>
  comment:
    width_percentage: <width relative to the terminal window>
    min_width: <width as number of characters>
  snippet:
    width_percentage: <width relative to the terminal window>
    min_width: <width as number of characters>

Overriding fzf options

You can override fzf options for two different cases:

  • During the cheats selection

    Navi exposes the overrides directive in the configuration file
    and the NAVI_FZF_OVERRIDES environment variable.

  • During the pre-defined variable values selection

    Navi exposes the overrides_var directive in the configuration file
    and the NAVI_FZF_OVERRIDES_VAR environment variable.

For all cases, navi exposes the FZF_DEFAULT_OPTS environment variable.

Overriding during cheats selection

If you want to do the override with --height 3,
you can do it with the following syntax in the configuration file:

yaml
finder:
  command: fzf
  overrides: --height 3

But you can also define the environment variable like this:

bash
export NAVI_FZF_OVERRIDES='--height 3'

Overriding during values selection

If you want to do the override with --height 3,
you can do it with the following syntax in the configuration file:

yaml
finder:
  command: fzf
  overrides_var: --height 3

But you can also define the environment variable like this:

bash
export NAVI_FZF_OVERRIDES_VAR='--height 3'

Overriding for all cases

You can define the environment variable like this:

bash
export FZF_DEFAULT_OPTS="--height 3"

[!NOTE]
See @junegunn/fzf for more details on $FZF_DEFAULT_OPTS.

Defining your own delimiter

Navi allows you to define your own delimiter to parse the selected result for a variable in your cheats.
It is equivalent to defining --delimiter used with --column.

You can define it as such:

yaml
finder:
  delimiter_var: <your-regex-delimiter> ### By default the expression is \s\s+

[!CAUTION]
Defining the delimiter via the configuration file means that Navi will use this delimiter by default for
every variable using the --column instruction.

You can override this configuration with the --delimiter instruction in the variable definition of your cheat.
See /docs/cheatsheet/syntax/ for more details.

Changing shell

You can change the shell that is used inside navi.

yaml
shell:
  command: bash
  finder_command: bash

shell.command is used to execute commands that generate possible values for variables.
shell.finder_command is used inside fzf.

For example, suppose you have the following cheat sheet.

text
# ISO 8061
date -I

$ iso_unit: echo -e 'date\nhours\nminutes\nseconds\nns'

The command echo -e 'date\nhours\nminutes\nseconds\nns' is executed in the shell specified by shell.command.

Use bash on Windows

On Windows, there are several bash environments available, including MSYS2's bash, Git Bash, and w64devkit's bash.
The w64devkit's bash isn't actually bash, but it can be used just like bash.
Here is an example of using Git Bash.

yaml
shell:
  command: "\"C:/Program Files/Git/bin/bash.exe\""
  finder_command: "C:/Program Files/Git/bin/bash.exe"
  forward_slash_path: true

If the path to the executable contains spaces, it must be quoted in the shell.command.
Unlike shell.command, shell.finder_command does not require the path to be quoted even if it contains spaces.
Additionaly, shell.forward_slash_path must be set to true.
shell.forward_slash_path: true can be used with bash environments that interpret paths with forward slashes (e.g., C:/path/to/bash.exe).
Other than Windows, setting shell.forward_slash_path has no effect.

File: docs/cheatsheet/repositories/README.md

Cheatsheet repositories

About

Navi lets you work with what we call cheatsheet repositories, they are git repositories
and mainly consists of .cheat files.

This page is dedicated to the information you might need to work with cheatsheet repositories.

Importing cheatsheet repositories

You can import cheatsheet repositories with the repo add subcommand.
See /docs/usage/commands/repo for more details.

Submitting cheatsheets

The featured repository for cheatsheets is denisidoro/cheats,
feel free to open a PR[^1] there for me to include your contributions.

In order to add your own repository as a featured cheatsheet repo, please edit this file and open a PR[^1].

Auto-updating repositories

Right now, navi doesn't have support for auto-updating out of the box.
However, you can achieve this by using git and crontab.

  • First make sure you cloned your repo using git to the correct folder:

    sh
    user=""
repo="<repo>"
git clone "https://github.com/${user}/${repo}" "$(navi info cheats-path)/${user}__${repo}"

  • Then, add a cron job:

    sh
    crontab -e
*/0 11 * * * bash -c 'cd "$(/usr/local/bin/navi info cheats-path)/__<repo>" && /usr/local/bin/git pull -q origin master'

[!NOTE]
Please note the cron job above is just an example AND you should edit it accordingly:

  • In this example, the cron job is triggered every day at 11am.

    You might want to check out crontab guru regarding crontab.

  • The full paths to navi and git may differ in your setup.

    Check their actual values using which as which .

  • Don't forget to replace __<repo> with the actual folder name

[^1]: A PR is short for Pull Request

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#bash Browse bash catalog → #cheatsheets Browse cheatsheets catalog → #cli Browse cli catalog → #command-line Browse command-line catalog → #rust Browse rust catalog → #shell Browse shell catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →