⚡ blaze-keys

Blazing fast terminal commands with customizable leader-key combos and project-specific keybinds. For Zsh and Nushell.

nushell support is limited to leader-key functionality at present.

Demo

Note: All the keybinds shown are defined in the blz config, and fully customizable.

Introduction

With blaze-keys you can:

• Easily assign hotkeys to execute commands in Zsh, like setting Alt+g to run git status.
  • Define different hotkeys for different projects generically, which automatically reassign as you move between projects.
• Define leader key combos in Zsh/Nushell which can:
  • Execute commands with minimal key presses, and without leaving the home row - useful for commands like git status or cargo build --release.
  • Expand into the current line to allow you to add arguments - useful for commands like git commit -am or git checkout -b.
  • Run zsh builtins, like the useful push-line.
• Easily customise hotkeys and leader combos to your preferences.
  • Set multiple leader keys which activate different combos.
  • Explore your leader key combos with the TUI, which is only ever one hotkey away.

For example, maybe you want to be able to use Shift+Alt+B to run cargo build in a Rust project, but you want the same shortcut to run make in a C project. blaze-keys allows you to easily configure this, without needing to run any commands when you cd between projects.

Tip: blaze-keys also works in Vim mode; call bindkey -v before activating blaze-keys in your ~/.zshrc.

Future work

• Improve macOS support (please see the issue).
  • It should work fine on macOS (it has been tested briefly), but I'm in no position to guarantee this - especially for different terminal emulators.
• Support other shells, such as fish (please upvote the issue if you're interested).
  • Preliminary support for nushell added. Limitations: blz only supports leader keys in nushell; top-level keybinds are not yet supported.

Try it out with Docker?

You can try out blaze-keys without installing it, by using the Docker image.

Configuration

blaze-keys uses two types of configuration:

• The global configuration:
  • Contains keybindings which are always applied.
  • Defines profiles which contain sets of keybindings for different types of projects.
    • Profiles can define conditions which are used to determine whether they should be applied when you cd into a project.
  • Defines leader-key combos.
• local configurations (optional):
  • Contain keybindings which are applied only when the local configuration is in your current working directory.
  • Can inherit a profile from the global config.

Quick start guide

After completing the setup steps below, you can follow the brief tutorial.

1. Download 'blz'

blz is a single executable file in a tarball, which you can download from the release page. Extract blz from the tarball and make sure it's on your PATH.

You can alternatively install with cargo (Rust 1.88 or newer):

cargo install --locked --bin blz blaze-keys

2. Configure global config

Run blz -g to edit the global config (creating from template if not present). The repo includes an example which demonstrates many of the available features: global.all.yml. I would suggest that you use the all config when prompted, then (after completing step 3 below) follow the tutorial to familiarise yourself with the usage; then you can modify the config as you wish.

Warning: After adding a new leader key to the global config, you need to source your config (in Zsh) or open a new shell for the new keybinds to take effect.

3. Configure shell integration

⚠️ macOS users: You will need to configure your terminal emulator to use the Option key as Alt. Please see the macOS terminal setup guide for more information.

Zsh - Update .zshrc

For zsh, add a line to your .zshrc file and source it:

echo 'source <(blz --zsh-hook)' >> ~/.zshrc
source ~/.zshrc

Nushell - Update nu config

If using nushell, first you need to generate the file which will hold the leader-key keybindings:

# Important: Run manually before adding the block to the nu config.
blz porcelain generate-nu-source

Then run config nu to edit the shell config, and paste in the following block:

### blaze-keys: start v1
blz porcelain generate-nu-source
source ~/.config/blaze-keys/.leader_keys.nu
$env.BLZ_SHELL = "nu"
$env.BLZ_LEADER_STATE = (blz porcelain print-leader-state)
$env.config.hooks.pre_execution = $env.config.hooks.pre_execution | append { ||
  if ((commandline) | str contains "source") {} else if ((commandline) | str contains "env.BLZ") {} else {
    blz porcelain check-leader-state
  }
}
### blaze-keys: end

Then open a new shell. You will need to use a new terminal tab/window to ensure it doesn't inherit the environment from the first shell.

4. (Optional) Configure local config

Note: Local configs are optional, and I would typically recommend creating a profile in the global config instead.

You can use blz -l to edit (creating if not present) a local config in any directory, which will be stored as .blz.yml. It will be applied only when you cd to that directory.

# Optional: You can inherit a profile from the global config. 
# This isn't necessary if one of the profile's 'conditions' evaluates to true.
inherits:
  - Rust

keybinds:
  - key: "Ctrl-l"
    command: "ls -la"
  - key: "C-g"
    # '^M' can be used as the `Enter` key. This is useful here because `blz` applies only one `^M`, 
    # which in this case expands `!!` to the last executed command; 
    # another 'Enter' is required to execute the expanded last command.
    command: "!!^M"   
  - key: "F10"
    command: "cargo run"

FAQs

What features are supported in nushell?

The leader-key functionality is supported in nushell, but top-level keybinds are not yet.

If I cd into a child directory, will my keybindings be unset?

Every time you cd, blz will emit the appropriate keybindings based on the local config, if present, and any profiles in the global config, if applicable. It does not explicitly unset any keybindings when a local config or profile becomes non-applicable, so your keybindings will remain set until a conflicting keybind is applied.

Why use the leader-key functionality of blaze-keys instead of shell aliases?

• You can 'overload' aliases by putting them behind different leader keys, to avoid clashes e.g. where you would like cc to run cargo check or conan create.
• You can execute commands without needing to move your hand to reach the Enter key (exec mode). In my experience, this reduces strain on my wrist significantly.
• You can use an alias which expands into the current command line (abbr mode). Unlike an alias, the full command will appear in your history.
• You can create postfix aliases, e.g. if you often work with a Docker image localhost/my-private-image, you can create an alias with blaze-keys which can be used after typing the initial command, like docker save -o out.tar <trigger blaze-keys to insert 'localhost/my-private-image'>.
• The blaze-keys TUI makes it easier to find an alias which you've forgotten, rather than searching for it in the alias output.
• Subjectively, using blaze-keys just feels like you have a more direct interface with the terminal. It feels smoother and more fluid, partly because the Enter key becomes more obsolete.

How do I diagnose problems?

If your top-level keybindings are not working as expected, you can see what keybindings are being emitted by running blz -v:

$ blz -v
Ctrl-P  ----->  'push-line' (zle builtin)
Alt-l   ----->  'ls -lah'
F2      ----->  'git log'
Alt-B   ----->  'cargo build'
Alt-X   ----->  'cargo run'
...

Note: This is directory-dependent and will include all keybindings from profiles active in your current working directory, or local configs.

You can run blz -B to see the raw bindkey commands which are being executed, in Zsh syntax. You can then manually try to run these bindkey commands to see if they work.

If your TUI is not appearing when triggering a leader key, check for a .panic.blz file in the current working directory.

Logs

If you need to view blz logs, you can export BLZ_LOG=debug and view the log file at /tmp/blz.log.

What are the security risks?

It's possible for another process to inject into the command which is completed with blz, if specifically engineered to do so. However, this is no greater risk than that of a program overwriting your ~/.zshrc to reassign some aliases to malicious commands.

As a precaution, blz will not run as root unless an environment variable (BLZ_ALLOW_ROOT) is explicitly set.