https://github.com/kencx/keyb
Create and view custom hotkey cheatsheets in the terminal
https://github.com/kencx/keyb
bubbletea cheatsheet command-line hotkeys keybindings keyboard-shortcuts keymappings terminal tui
Last synced: 5 months ago
JSON representation
Create and view custom hotkey cheatsheets in the terminal
- Host: GitHub
- URL: https://github.com/kencx/keyb
- Owner: kencx
- License: mit
- Created: 2022-01-15T05:17:44.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-06-28T15:52:49.000Z (12 months ago)
- Last Synced: 2025-06-28T16:48:28.150Z (12 months ago)
- Topics: bubbletea, cheatsheet, command-line, hotkeys, keybindings, keyboard-shortcuts, keymappings, terminal, tui
- Language: Go
- Homepage:
- Size: 48.8 MB
- Stars: 218
- Watchers: 3
- Forks: 6
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
I also wrote a blog [post](https://blog.cheo.dev/posts/keyb) about building 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](https://github.com/kencx/keyb/releases) page.
### Install with Go
```bash
$ go install github.com/kencx/keyb@latest
```
### Build from source
```bash
$ git clone https://github.com/kencx/keyb
$ cd keyb
$ make build
```
## Usage
```text
usage: keyb [options]
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:
```bash
$ 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.
```yaml
- 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.
```yaml
- 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!
### Quick Add
```text
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.
```bash
$ 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 can be customized with a config file at the default OS config
directory (i.e. `$XDG_CONFIG_HOME/keyb/config.yml`). If no such file exists, the
default configuration will be used.
See [config](examples/config/README.md) for all configuration options.
### Missing Colors
If you're missing colors, a workaround is to add the environment variable `CLICOLOR_FORCE=1` to
[force ANSI color support](https://pkg.go.dev/github.com/muesli/termenv#Output.EnvColorProfile).
## Roadmap
- [x] Ability to customize keyb hotkeys
- [x] `a, add` subcommand to quickly add a single hotkey entry from the CLI
- [ ] Export to additional file formats (`json, toml, conf/ini` etc.)
- [ ] Support multiple keyb files or directories
## Contributing
keyb requires Go 1.22. Bug reports, feature requests and PRs are very welcome.
## Similar Tools
- [showkeys](https://github.com/adamharmansky/showkeys) offers a keybinding popup similar to awesomewm
- [cheat](https://github.com/cheat/cheat) is a CLI alternative to view cheatsheets for
commands and hotkeys for just about any topic
- Refer to [shortcut-pages](https://github.com/mt-empty/shortcut-pages), [cheat/cheatsheets](https://github.com/cheat/cheatsheets) for more cheatsheets
## License
[MIT](LICENSE)