DOCSEARCHbyAlgolia
Submit Docs

navi

repository·master·Indexed 12 days ago

https://github.com/denisidoro/navi

An interactive command-line cheatsheet tool for browsing, searching, and executing complex commands. It integrates with fzf or skim to provide a dynamic interface for selecting command arguments and supports custom .cheat files, variable dependencies, and integration with tldr and cheat.sh.

Tokens
15K
Snippets
72
Records
87
Agent score
96%

What's inside navi

  1. What is Navi?

    master

    Navi is an interactive command-line cheatsheet tool. It allows you to browse through cheatsheets—either ones you have written yourself or those provided by maintainers—and execute the commands directly from your terminal.

    Navi is designed to reduce the need to memorize complex CLI flags, eliminate manual copy-pasting of intermediate command outputs, and help you discover new one-liners. It functions as both a standalone command and a shell widget (similar to the Ctrl-R functionality in many shells).

  2. Manage variable dependencies

    master

    Variables can depend on other variables in two ways:

    1. Implicit Dependencies

    Refer to another variable using the standard <variable> syntax. This is useful for constructing paths or concatenated strings.

    echo "<wallpaper_folder>"

$ pictures_folder: echo "/my/pictures"
$ wallpaper_folder: echo "<pictures_folder>/wallpapers"

    2. Explicit Dependencies

    Prepend a dollar sign ($) to the variable name in the pre-defined variable line. This allows you to use the value of one variable to generate the suggestion list for another.

    echo <x> <y>

# If you select 'hello' for <x>, <y> might suggest 'hello foo' or 'hello bar'
$ x: echo "hello hi" | tr ' ' '\n'
$ y: echo "$x foo;$x bar" | tr ';' '\n'

    Note: To ignore the contents of <x> and only print <y> in an explicit dependency, use the metacomment syntax: : <x>; echo <y>

    # Implicit dependency example
echo "<wallpaper_folder>"

$ pictures_folder: echo "/my/pictures"
$ wallpaper_folder: echo "<pictures_folder>/wallpapers"

  3. Define and customize variables in cheatsheets

    master

    Variables are defined using angle brackets (e.g., <variable_name>) within executable commands. To provide suggestions for these variables, use a line starting with $.

    Advanced Variable Customization

    You can use --- in a pre-defined variable line to pass parameters that modify how fzf behaves or how the variable value is processed.

    Supported Parameters

    ParameterDescription
    --column <number>Extracts a specific column from the command result.
    --map <bash_code>[EXPERIMENTAL] Applies a bash function to the selected value.
    --prevent-extra[EXPERIMENTAL] Limits the user to selecting only from the provided suggestions.
    --fzf-overrides <arg>[EXPERIMENTAL] Passes arbitrary arguments to fzf.
    --expand[EXPERIMENTAL] Converts each line of the result into a separate argument.

    Parameters forwarded to fzf*

    You can also pass these directly to fzf using ---:

    • --multi (for multiple selections)
    • --header-lines <number>
    • --delimiter <regex>
    • --query <text>
    • --filter <text>
    • --header <text>
    • --preview <bash_code>
    • --preview-window <text>

    *Note: Use these to customize the selection interface.

    # Example: Extracting a specific column
docker rmi <image_id>
$ image_id: docker images --- --column 3 --header-lines 1 --delimiter '\s\s+'

# Example: Mapping values (Experimental)
echo <mapped>
$ mapped: echo 'false true' | tr ' ' '\n' --- --map "grep -q t && echo 1 || echo 0"

# Example: Multiple arguments (Experimental)
cat <jsons>
$ jsons: find . -iname '*.json' -type f -print --- --multi --expand

  4. Extend cheats using tags

    master

    You can extend a cheat context by using the @ symbol followed by tags from other cheats. This allows different cheats to share the same context and variables.

    % dirs, common

$ pictures_folder: echo "/my/pictures"

% wallpapers
@ dirs, common

# Uses <pictures_folder> from the 'common' context
echo "<pictures_folder>/wallpapers"

% screenshots
@ dirs, common

# Also uses <pictures_folder> from the 'common' context
echo "<pictures_folder>/screenshots"
    % dirs, common

$ pictures_folder: echo "/my/pictures"

% wallpapers
@ dirs, common

# Should print /my/pictures/wallpapers
echo "<pictures_folder>/wallpapers"

  5. Choosing between queries and selection with variables

    master

    When navi prompts you to fill a variable value, you can choose between entering a custom query or selecting from a list of available options using keyboard shortcuts:

    • <kbd>tab</kbd>: Prefers the query (allows you to type/enter the value manually).
    • <kbd>enter</kbd>: Prefers the selection (chooses from the provided list).

  6. Manage cheatsheet repositories

    master

    By default, navi stores cheatsheets at ~/.local/share/navi/cheats/.

    Capabilities include:

    • Browsing: Explore featured cheatsheet repositories.
    • Importing: Add cheatsheets from Git repositories.
    • Writing: Create your own .cheat files.
    • External Tools: Use cheatsheets from tldr and cheat.sh.
    • Automation: Auto-update repositories or auto-export from TiddlyWiki using a plugin.

  8. Structure of Navi documentation

    master

    Navi's documentation is written in Markdown and is organized within the docs/ directory. The documentation follows a topic-based structure where each major topic is represented by a folder. To maintain discoverability, the structure separates source files and examples from the main topic files.

    Recommended Directory Hierarchy:

    • docs/<topic>/README.md: The main entry point for a specific topic.
    • docs/src/<topic-source-files>/: Contains the core documentation source files for a topic, further organized by type.
    • docs/examples/<topic-examples>/: Contains usage examples related to a topic.

    Best Practice: Avoid nesting documentation deeper than 3 levels to ensure ease of navigation.

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

  9. Write multiline commands and snippets

    master

    Navi supports multiline commands (snippets) in two ways:

    1. Standard Multiline: Use shell line continuations (e.g., \).
    2. Markdown Code Blocks: Wrap the command in triple backticks (```) inside the .cheat file.
    % bash, foo

# Using line continuations
echo foo
true \
   && echo yes \
   || echo no

# Using Markdown blocks
% git, code

# Change branch
```sh
git checkout <branch>

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

    % git, code

# Change branch
```sh
git checkout <branch>

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

  11. Import a cheatsheet repository

    master

    You can import entire cheatsheet repositories into navi using a standard git-clone format, such as an HTTPS URL or an SSH URI.

    Caution: When using navi repo add, the command ignores the $NAVI_PATH environment variable and uses default installation paths. If you want to install repositories into a specific directory defined by $NAVI_PATH, use a standard git clone command to clone the repository directly into that path instead.

    # Import using HTTPS
navi repo add https://github.com/denisidoro/cheats

# Import using SSH
navi repo add git@github.com:denisidoro/cheats

  12. Override FZF settings via command line arguments

    master

    You can pass specific FZF configuration flags to navi using command line arguments. Depending on your goal, use one of two flags:

    1. To override settings only when selecting snippets: Use the --fzf-overrides flag.
    2. To override settings only when selecting argument values: Use the --fzf-overrides-var flag.

    This allows you to customize the FZF interface (e.g., changing height, layout, or colors) specifically for the snippet selection phase or the variable interpolation phase.

    # Override only when selecting snippets
navi --fzf-overrides '--height 3'

# Override only when selecting argument values
navi --fzf-overrides-var '--height 3'