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

💪 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

• bash or zsh
• crossterm compatible terminal (see their Readme for a list)

Note: I personally use leadr in bash on Linux. I have tested it with zsh on Linux but have no way to test it on macOS. I'd be happy to get some feedback about how well leadr works in zsh, particularly on macOS.

📦 Installation

Note: This project is still in early development, expect some breaking changes every now and then.

You can download pre-built binaries from the releases page. Just copy the binary to a directory in your PATH and make it executable.

You can install leadr using cargo:

cargo install leadr

This will install the latest version of leadr from crates.io.

You can build leadr from source using cargo:

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

🐚 Shell Integration

To use leadr, simply add the following line to your shell configuration file (e.g. ~/.bashrc or ~/.zshrc):

# For bash
source <(leadr --bash)

# For zsh
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 keybinding, tweak the keybinding panel and other global settings. For a list of currently supported keybindings, see src/keymap.rs.

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: 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.