denisidoro/navi

An interactive cheatsheet tool for the command-line

navi

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, 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
• 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 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
• as an Alfred workflow

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 soted at ~/.local/share/navi/cheats/.

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
• auto-update repositories
• auto-export cheatsheets from your TiddlyWiki notes using a TiddlyWiki plugin

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:

• setup your own config file
• set custom paths for your config file and cheat sheets
• change colors
• resize columns
• change how search is performed

More info

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

navi --help

In addition, please check the /docs folder.

Similar tools

There are many similar projects out there (beavr, bro, cheat, cheat.sh, cmdmenu, eg, how2, howdoi, Command Line Interface Pages 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

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

navi's Issues

Add official brew formula

Related: Homebrew/homebrew-core#45695

grep: Invalid range end; syntax error near unexpected token `newline'

I see these two errors back to back after ever command I try.

repro:

1. invoke navi while in a directory that has a git repo
2. type git check
3. choose git checkout <branch> [git]

result:

22:20 $ navi
grep: Invalid range end
/opt/navi/src/main.sh: eval: line 35: syntax error near unexpected token `newline'

get the same result if I choose # Checkout to branch [git], or any other option at all such as netstat ..., tar xf <tar_file>, etc

environment:

OS: Ubuntu 18.04.3
shell: GNU bash, version 4.4.20(1)-release (x86_64-pc-linux-gnu)
grep: grep (GNU grep) 3.1
fzf: 0.18.0 (ff95134)

I noticed in the README mention of brew. is it possible this tool was built to run with BSD grep?

btw, this tool looks great! I've always wanted to make something very much like this. Thanks for building it!

Stop relying on tags to find snippet

As of now, to go from an FZF selection to a snippet, navi:

• gets the snippet + tags of the selection
• uses the tags to find a cheatsheet file
• searches for the snippet in a cheatsheet

This brings problems such as borking if a file has no tags and so on.

Getting readonly_variable error when running search command

If I run

navi search <anything>

I get

/opt/navi/src/opts.sh: line 43: wait_for: readonly variable

This is on Arch Linux, navi version 0.8.1, zsh shell. Same things happens if I switch to bash.

I didn't manage to find a related issue, so I'd appreciate any input on what might be wrong. I suppose the cause is #12 thought?

Thanks.

Edit: Actually, I was blind and didn't see I also get it when I just run normal navi, but there it's line 44, same exact error. The command itself works though, in that case.

Variable suggestion window does not show when upgrade navi from v0.11.1 to v0.12.0

Reproduce steps:

1. input git checkout
2. press Enter key
3. Got following error:
   Unable to fetch suggestions for 'branch'!

Environment:
mac
iterm2
zsh
fzf: 0.17.1 (brew)

Escape $(...) in cheatsheets

docker rm -f $(docker ps -aq) will execute docker ps -aq when highlighted in FZF ⚠️

Zsh Widget on macOS

I'm working on my macOS terminal. And I can not activate navi widget on zsh with alt+g hotkey.
I'm not sure whether it has something to do with the alt key on Apple keyboard layout. Can I change the default activation hotkey?

Not enough issues, not professional enough

Not enough issues, not professional enough

fzf package missing.

After installing navi using sudo make install, and running using navi I get this error:

/opt/navi/src/ui.sh: line 4: fzf: command not found

And after running sudo apt install fzf it worked fine.

Allow variable names to include dashes or spaces

It's not evident that variables should only contain alphanumeric characters and underscores.

Using spaces and dashes would make variable references in scripts non trivial, though (eg "image name" would become "image_name").

Validate argument names

The script should be aborted if a regex isn't matched, to avoid arbitrary code execution

Remove dependency on brew in scripts/release

Calculating the sha256 by hand should be possible without brew

Color scheme for light background

Hi,

Navi is sweet, thanks for making it :)

I have a white background in my terminal, and unfortunately the default color scheme is not quite as readable as a dark background. Is it possible to get an option or environment variable for a different color scheme that would work better on light backgrounds?

Thanks!

Is this for Mac? Can't install on Ubuntu 18.04 x86_64 bit

After
git clone http://github.com/denisidoro/navi /opt/navi
sudo git clone http://github.com/denisidoro/navi /opt/navi
cd /opt/navi
Everything is normal.
But after
sudo make install
It outputs
scripts/install and I can't invoke navi.

The output after invoking navi is
/opt/navi/src/ui.sh: line 4: fzf: command not found
grep: Invalid range end

Print command before executing, add to history

Hi @denisidoro,

Is it possible to get a flag to show the command before it gets executed. It would be even better if it could be added to shell history, so it can be quickly recalled.

Thoughts?

Thanks 🙏

Change license

Is there a chance the license to be changed?
Some big tech companies have AGPL-3 blacklisted.

Auto-select on single option

If there's a single option available, fzf shouldn't be prompted. The single value should be auto-selected.

A --no-autoselect could be added as well.

Run last printed command

Well done! Awesome project!!

This project bring new answer for the question What is cheatsheet for Linux?

Since that everything is good. In my opinion, default behaviour is not safe since it's runs selected command even knowing what is command.

For example if I will use docker rmi command to additionally navi runs
$ docker images --- --headers 1 --column 3 and select argument by column base selector.

Any mistake in this process like

• Column base selector may will not give correct parameter due to special character etc.. (Or output change for application)
• User can make mistake while selecting command
• User can make mistake selecting image column

In this cases user can delete wrong things and this can create problem for user.

Absolutelly I understand this is not your responsibility and also you mentioned also in the help page. To being safe and secure use --print option.

To prevent those problems, I wrote 2 simple bash function which could be new feature for this project.

function naviprint()
{
    PRINT_OUTPUT=$(navi --print)
    export NAVI_LAST_COMMAND=$(echo $PRINT_OUTPUT)
    echo "$NAVI_LAST_COMMAND"
}

# Can be as used as navi lastcommand
function navilast()
{
    eval $NAVI_LAST_COMMAND
}

Thank you for your effort!

Best Regards,
Enis

Multiple options in a single command

Hi, Love the project.

Was expecting the following to work:

% fileinsubdir

# Cat a file in a subdir
cat -f <dir>/<file>

$ dir: find . -maxdepth 1 -type d --- --column 1
$ file: find "$dir" -maxdepth 1 -type f --- column 1

However it just prompts me for input

$ navi
dir file:

I think it thinks there's one option called "dir file" instead of two?

Likewise the MySQL ones just prompt for

$ navi
user database path:

And even entering three values, seperated by spaces just causes it to keep printing out the same thing until ^C.

Tried with both HEAD and v0.9.2

Support Windows (cmd/Powershell)

Please add support to Windows (Choco, curl)

Prevent printing result in some cases when --no-interpolation

Printing without specifying --print should occur if, and only if, there are unresolved arguments

Recv failure: Connection reset by peer?

I tried use the git clone command with sudo on Ubuntu18.04, and then get this:

Cloning other projects is OK. How to fix this?

Integrate with cheat.sh

navi --cheatsh awk could browse the snippets for awk defined on http://cheat.sh/ for example

Fix argument expansion when installing with make install

There are missing double quotes. I think it will allow at most 1 argument as-is.

Unable to find command for '<anything>'

When I call navi from command line I always get "Unable to find command for '...".
It seems like navi is ignoring the first character under selected item. Refer to image, please.

I have just cloned the repo and tried whith the navi executable.

git clone [email protected]:denisidoro/navi.git
cd navi
./navi

Create widgets for bash+zsh+fish

Hitting Ctrl-G for example could start the script.

When selecting an entry, instead of executing it, it could fill the prompt (similarly to ctrl-r).

This way the history will be kept clean and there will be the possibility to edit the command as you like.

Edit: this is done for zsh, bash and zsh already!
Please refer to README.md.

Store cheatsheets in memory

Instead of running cat $cheat, we could call a function such as memoized_cat so that we don't need to perform IO on each keypress.

We could additionally store a map going from tags to a cheatsheet.

how

Invalid when command contains "^"

Add command ls -lR|grep '^-'|wc -l to a cheat file and choose it. Error info "No valid cheatsheet!"

lack the ability to redirect the output of command

tac command in OSX

Hello, tac command is not available by default in OSX. Maybe it's worth a mention in the README, as a requirement if you use the shell widget option.

Why variables only support numbers and no strings

great tool and some suggest
I think you can add a variable support string and suggest that possible values for a given argument can be entered instead of not returning directly.

Deploy to AUR

Would love to have this on Arch's User Repository (AUR).

Let me know if you want me to write and maintain a git-based MAKEFILE for you (example).

Correctly (un)escape double-quotes and \n in .cheat

Support skim?

I've been using skim for a while now, and if I change the commands from fzf to sk, it invokes fine, but interactive searching doesn't work so well. I'm sure there are some differences between -i in both tools, but do not know how to move forward.

Ability to set multiple arguments

Take this snippet for example:

# Copy file/s from source to destination
cp <source> <dest>

$ source: ls
$ dest: ls

This simply breaks the whole operation of the script.

how to use in linux?

anyone who can tell me how to use it in centos7 ? i can not install it in linux ,it did not work

Add option to call a snippet directly

navi best “primary ip" could automatically execute the snippet which best matches the query, for example.

Flags such as --print should still work accordingly.

create database error

When I use navi to create database, an error occur like below:
/opt/dry/navi/src/main.sh: line 35: database: unbound variable

I use Mac iTerm, and my operation step is as below:

1. input navi in the iTerm
2. input create database, then press Enter
3. input root after user: , then press Enter

then, the result is as below:

➜  cheats git:(master) navi
/opt/dry/navi/src/main.sh: line 35: database: unbound variable

Multiline commands

Hi @denisidoro,

Any chance of supporting multiline commands, such as:

command abc xyz \
  --param1 foo \
  --param2 bar

Or some other method of running more complex commands (think involved things with pipes).

Thanks 🙏

fail replacement using sed regex references group

Hi,

Thanks for the project.

I have noticed a bug when I use the binding ctrl+g in bash.
This command in a cheat fails because it replaces the \1 by ^A

In my cheat it's

# Find primary, local IP address
ip -o route get to 8.8.8.8 | sed -n 's/.*src \([0-9.]\+\).*/\1/p'

The command parsed after the binding is
ip -o route get to 8.8.8.8 | sed -n 's/.*src \([0-9.]\+\).*/^A/p'

Terminal: tilix
bash 5.0.11

Thanks !

Issue with quoting

Hi @denisidoro,

It seems that right now, parameters are always enclosed in quotes. While this works in most cases, it makes it hard to do simple commands like:

curl http://example.com/<arg1>/foo/<arg2>

The resulting command would be:

curl http://example.com/"value1"/foo/"value2"

Instead of simply:

curl http://example.com/value1/foo/value2

Ideas?

Thanks.

fail conda activation

When I use conda activate <env> in zsh, and type env: base. It failed.

1. I already followed the steps in the steps in Installation using oh-my-zsh and added export PATH=$PATH:"$ZSH_CUSTOM/plugins/navi" in my ~/.zshrc.

2. I also tried and conda init zsh. It doesn't work.

Here are Error commands:

CommandNotFoundError: Your shell has not been properly configured to use 'conda activate'.
To initialize your shell, run

    $ conda init <SHELL_NAME>

Currently supported shells are:
  - bash
  - fish
  - tcsh
  - xonsh
  - zsh
  - powershell

See 'conda init --help' for more information and options.

IMPORTANT: You may need to close and restart your shell after running 'conda init'.

ho

Preview command

Use fzf's --preview flag so that you know what you'll run

OSX: zsh: command not found: navi

When following the oh-my-zsh instructions I run into an issue where the command is not found. zsh: command not found: navi This prevents me from being able to use it as a widget. Are the instructions missing a step, am I supposed to link the executable in /usr/bin/local or something so that its available? If I install it using homebrew the command is available and will execute but the instructions are not clear on whether or not I have to follow two of the three possible steps to get it working properly.

Support install without sudo permissions?

Is it possible to have an install route without the need for sudo?

Missing from Homebrew?

I can't find any record of Navi being a Homebrew package.

~/P/A brew update
Already up-to-date.

~/P/A/ brew install navi
Error: No available formula with the name "navi"

I search https://brew.sh/ for good measure.

The documentation doesn't say anything about a special formula, and I don't see a formula definition in the repo at first glance.

Am I missing something?

Missing LICENSE

There is no LICENSE or COPYING file for this project. The default is copyright.

You should license this project under the AGPL3 or GPL3 license. Directions on how to apply the license are at the bottom of the license file under the How to Apply These Terms to Your New Programs heading. There is a helpful guide for the GPL at https://www.gnu.org/licenses/gpl-howto.en.html. If you would like me to submit a PR to make this easier, I would be happy to do that.

Add back support for alpine

Since #47, navi won't work on alpine
I think it's related to sed