keyb

Create and view your own custom hotkey cheatsheet in the terminal

Features

• Lightweight and quick
• Fully customizable
• Fuzzy filtering
• Vim key bindings
• Export to stdout for fzf, rofi support

Non-Features

keyb does not support:

• Auto detection of hotkeys
• Command selection

Motivation

I had trouble remembering the various hotkeys that I sometimes use. It got annoying to look them up so I resorted to writing them down on a paper cheatsheet. Then, I thought: maybe there's a tool that does this better. I didn't find one I liked so I built keyb.

With keyb, I can list:

• Hotkeys that I occasionally forget or am new to
• Custom key combinations that I defined for my own workflow
• Short commands that I sometimes use

It is best used as a popup cheatsheet.

Install

keyb supports Linux, MacOS and Windows.

Compiled Binary

Download a compiled binary from the releases page.

Install with Go

$ go install github.com/kencx/keyb@latest

Build from source

$ git clone https://github.com/kencx/keyb
$ cd keyb
$ make build

Usage

usage: keyb [options] <command>

Options:
  -p, --print     Print to stdout
  -e, --export    Export to file
  -k, --key       Key bindings at custom path
  -c, --config    Config file at custom path
  -v, --version   Version info
  -h, --help      help for keyb

Commands:
  a, add          Add keybind to keyb file

Search

• Enter search mode with / to perform fuzzy filtering on all rows
• Exit search mode again with Esc
• Alt + d clears the current filter

To perform filtering on section headings only, prefix the search with h:. This will return all matching section headings with their respective rows.

Printing

keyb supports printing to stdout for use with other tools:

$ keyb -p | fzf
$ keyb -p | rofi -dmenu

keyb File

keyb requires a yaml file with a list of hotkeys to work. A default file is generated in your system's config directory if no other file is specified.

Hotkeys are classified into sections with a name and (optional) prefix field. When displayed, sections are sorted by alphabetical order while the keys themselves are arranged in their defined order.

- name: bspwm
  keybinds:
    - name: terminal
      key: Super + Return

The prefix is a key combination that will be prepended to every hotkey in the section. A key can choose to opt out by including a ignore_prefix: true field. Prefixes are useful for applications with a common leading hotkey like tmux.

- name: tmux
  prefix: ctrl + b
  keybinds:
    - name: Create new window
      key: c
    - name: Prev, next window
      key: Shift + {←, →}
      ignore_prefix: true

Refer to the examples for more examples.

Multiline fields are not supported at the moment.

Quick Add

usage: keyb [-k file] add [app; name; key]

Options:
  -b, --binding  Key binding
  -p, --prefix   Ignore prefix

You can quick add bindings from the command line to a specified file. If -k file is given and exists, the new keybind will be appended to the file. Otherwise, keyb_path defined in config.yml will be used.

$ keyb add -b "kitty; open terminal; super + enter"

When adding a new keybind, the app name, keybind name and keybind must be specified. It is separated by ; and wrapped in quotes (to prevent parsing errors).

Configuration

keyb is customized with a config.yml file that is automatically generated in the system's config directory.

By default, the following options are included.

Option	Default	Description
keyb_path	OS-dependent (see below)	keyb file path
debug	false	Debug mode
mouse	true	Mouse enabled
reverse	false	Swap the name and key columns
search_mode	false	Start in search mode
sort_keys	false	Sort keys alphabetically
title	""	Title text
prompt	"keys > "	Search bar prompt text
prompt_location	"top"	Location of search bar: top, bottom
placeholder	"..."	Search bar placeholder text
prefix_sep	";"	Separator symbol between prefix and key
sep_width	4	Separation width between columns
margin	0	Space between window and border
padding	1	Space between border and text
border	"hidden"	Border style: normal, rounded, double, thick, hidden

If set, XDG_CONFIG_HOME will be used in Unix and Darwin systems. Otherwise, keyb will fall back to the default OS config directory:

• Unix: $XDG_CONFIG_HOME/keyb/keyb.yml,
• MacOS or Darwin: $HOME/Library/Application Support/keyb/keyb.yml,
• Windows: %Appdata%\keyb\keyb.yml

Color

Both ANSI and hex color codes are supported.

Color Option	Default	Description
prompt	-	Prompt text color
cursor_fg	-	Cursor foreground
cursor_bg	-	Cursor background
filter_fg	"#FFA066"	Filter matching text foreground
filter_bg	-	Filter matching text background
counter_fg	-	Counter foreground
counter_bg	-	Counter background
placeholder_fg	-	Placeholder foreground
placeholder_bg	-	Placeholder background
border_color	-	Border color

Hotkeys

Multiple keys may be set for a single binding, separated by commas.

Hotkey	Default	Description
up, down	j, k / Up, Down	Move cursor
half_up, half_down	Ctrl + u, d	Move half window
full_up, full_down	Ctrl + b, f	Move full window
top, middle, bottom	H, M, L	Go to top, middle, bottom of screen
first_line, last_line	g, G	Go to first, last line
search	/	Enter search mode
clear_search	Alt + d	Clear current search (remains in search mode)
normal	Esc	Exit search mode
quit	Ctrl + c, q	Quit

Roadmap

• Ability to customize keyb hotkeys
• Export to additional file formats (json, toml, conf/ini etc.)
• a, add subcommand to quickly add a single hotkey entry from the CLI
• Automatic parsing from online cheatsheet repos (eg. cheat/cheatsheets)

Contributing

keyb requires Go 1.18.

Bug reports, feature requests and PRs are very welcome.

More examples for default keymaps in examples/ are also welcome.

Similar Tools

• showkeys offers a keybinding popup similar to awesomewm
• cheat is a CLI alternative to view cheatsheets for commands and hotkeys for just about any topic
• Refer to shortcut-pages, cheat/cheatsheets for more cheatsheets

License

MIT