leadr

leadr is a customizable CLI command manager inspired by the leader key concept in (Neo)Vim. Use memorable key sequences to quickly execute or insert commands in your terminal.

🚀 Demo

https://github.com/user-attachments/assets/ace9ec1c-0976-4868-abe9-a7499101c03a

💪 Features

• Customizable Mappings: Define your own key sequences to set your prompt.
• Insert or Execute: Immediately execute git status or just insert git commit -m "" ready for you to fill in.
• Prepend/Append: Forgot sudo? Just prepend it to the your prompt and keep typing.
• Surround: Wrap your current command in quotes or use $(command substitution) in the blink of an eye.
• Cursor Positioning: Automatically place your cursor at the right position after inserting or replacing commands.
• Evaluate pre-insert: Need the current date in your file name? Evaluate a command, then insert it.
• Keybinding Panel: In case they slipped your mind, see available mappings in a fancy looking pop-up.

🎮 Usage

After installing leadr, you can start using it by pressing the leadr keybinding followed by a key sequence.

With the default config, you can e.g. execute git status by pressing <Ctrl-g> followed by gs. Similarly, you can pre-populate git commit -m "" by pressing <Ctrl-g> followed by gc. Notice how your cursor is placed in between the double quotes? Neat, right?

But that's not all! <Ctrl-g>ps will prepend sudo to your currently typed command, <Ctrl-g>y will append a pipe to the system clipboard.

Want me to continue? Alright: <Ctrl-g>id will insert the current date wherever your cursor is, <Ctrl-g>sq will surround your current command in quotes.

You can get the tl;dr of all this by running

leadr --list

which will show you a list of all available mappings and their descriptions.

Consult the Configuration section to learn how to make leadr your own.

⚡️ Requirements

• A supported shell: bash, fish, nushell or zsh
• crossterm compatible terminal (see their Readme for a list)

📦 Installation

cargo install leadr

brew tap ll-nick/leadr
brew install leadr

git clone https://github.com/ll-nick/leadr.git
cd leadr
cargo install --path .

🐚 Shell Integration

To use leadr, simply add the following to your shell configuration file:

# ~/.bashrc
source <(leadr --bash)

# ~/.config/fish/config.fish
leadr --fish | source

# nushell/config.nu
mkdir ($nu.data-dir | path join "vendor/autoload")
leadr --nu | save -f ($nu.data-dir | path join "vendor/autoload/leadr.nu")

# ~/.zshrc
source <(leadr --zsh)

🛠️ Configuration

To get started configuring leadr, run leadr --init to create the default configuration files and start tweaking from there.

To overwrite the default configuration directory (see the directories crate for the default value of the config_dir) you can set the LEADR_CONFIG_DIR environment variable to your desired path.

config.toml

The main configuration file to set your leadr key, tweak the keybinding panel and other global settings. Most of these settings should be self-explanatory but here are some notes on a few of them:

leadr_key

The default keybinding is <C-g> (the Ctrl key and the g key pressed in one chord), but you can change that by modifying the leadr_key in the config.toml file. The syntax mimics that of Vim's keybindings, e.g. <M-x>, <C-s>, <F5>, etc. and supports (with the exception of nushell) chains like <C-x><C-s>abc.

Fair warning: Keybindings in the shell are a bit of an arcane mess. I asked my good friend Chad Gibbidy to help me out with this. Lots of bindings work but some don't. Feel free to experiment but if you run into issues, Ctrl + a letter is probably your safest bet.

redraw_prompt_line

Note: This setting concerns only bash users. It has no effect in other shells.

Due to the way key bindings work in bash, the current prompt line will disappear while leadr is activated. To cover this up, leadr will redraw it after start-up. If you experience issues with this, you can disable it by setting redraw_prompt_line = false.

Mappings

Mappings are defined in the mappings.toml file located in the leadr config directory. If you prefer some more structure, you can also create a mappings/ directory and define your mappings in separate and arbitrarily nested toml files inside that directory.

A mapping looks like this:

[abc]
command = "my-command"
description = "My optional command description"
insert_type = "Append" # See below for options, default: "Replace"
evaluate = true # Default: false
execute = true # Default: false

The only required field is command (and the key of course). All other fields will use their default values if not specified.

You can customize the behavior of the mapping by specifying insert_type, evaluate, and execute options. Here's an overview of the available options:

The cursor position after inserting or replacing commands can be customized by adding #CURSOR to the command. For the git commit -m "" example, define the command as git commit -m "#CURSOR" to place the cursor between the double quotes after inserting the command. This works for all insert types but will have no effect if evaluate or execute is set to true.

Note: For bash and zsh, execute works best inside a tmux session since it can utilize tmux's send-keys to execute commands. Outside of tmux, leadr will fallback to eval and manually append the command to the shell's history.

Keybinding Panel

leadr comes with a user interface that looks suspiciously similar to which-key. It is activated by default and will pop up shortly after pressing the leadr keybinding.

You can customize the panel by modifying the panel section in the config.toml file.

Color Theme

The default color theme uses the catppuccin mocha color palette. You can customize the colors by modifying the theme_name in the panel section of the config.toml file.

All catppuccin flavors are builtin and can be activated by setting theme_name to catppuccin-{flavor}.

Custom themes can be defined by adding themes/theme-name.toml in the leadr config directory. To e.g. create a high contrast theme, add themes/high-contrast.toml with the following content:

accent = { r = 255, g = 255, b = 0 }
background = { r = 0, g = 0, b = 0 }
text_highlight_primary = { r = 255, g = 0, b = 0 }
text_highlight_secondary = { r = 255, g = 255, b = 255 }
text_primary = { r = 255, g = 255, b = 255 }
text_secondary = { r = 192, g = 192, b = 192 }

and set theme_name = "high-contrast" in the config.toml file.

❤️ Contributions

Thanks @Banh-Canh for contributing the fish integration!
Thanks @johnallen3d and @bjohnso5 for testing leadr on macOS!
Thanks @ltaupiac for setting up the Homebrew tap!
Thanks @johnstegeman for improving the fish shell key parsing!