alf — Alias & Function CLI Searching Tool

A Rust TUI to rediscover your custom shell aliases & functions.

• additional image link

Installation

From Crates.io

cargo install alf_tui

Using Mise

# Prebuilt binary from the GitHub releases
mise use -g github:metal-gabe/alf-cli

# Or build from the published crate
mise use -g cargo:alf_tui

Using Homebrew

brew tap metal-gabe/alf
brew install alf

From Source

cargo install --git https://github.com/metal-gabe/alf-cli

Quick Start

1. First-time setup: Run the initialization wizard

   alf init
   

2. Launch the search interface:

   alf
   

[!TIP]

After installing, alf can be run right away. Using the init command creates a starting config file for you to be able to customize.

Configuration

Configuration file location (created after alf init):

• Linux: ~/.config/alf/config.toml
• macOS: ~/.config/alf/config.toml
• Windows: %USERPROFILE%\.config\alf\config.toml

Available Commands

• alf - Launch interactive TUI (default, no subcommand)
• alf search <QUERY> - Launch TUI with an initial search query pre-filled
• alf init - First-run configuration wizard
• alf init --print-shell-hook <SHELL> - Print the shell wrapper and exit (non-interactive equivalent of alf activate <SHELL>)
• alf activate <SHELL> - Print shell integration wrapper (zsh or bash)
• alf config add <PATH>... - Add one or more shell source files to shell_files (e.g. alf config add ~/.work_aliases); paths must be absolute or start with ~/$HOME, and must already exist
• alf config show - Display current configuration
• alf config edit - Open config in editor
• alf config reset - Reset to defaults

Configuration Options

Running alf init writes a config.toml like the one below.

The shell_files list is filled in with the shell files detected in your home directory (plus any you add during the wizard), and theme reflects your menu choice; every other value is the built-in default.

The comments are annotations for this README and are not written to the generated file.

[display]
show_type_badges = true      # show Alias/Function badges
syntax_highlighting = true   # syntax highlight in detail view
parse_comments = true        # parse and display comments from shell files

[general]
shell_files = ["~/.bashrc", "~/.zshrc"]  # detected at init; glob patterns supported
alias_expansion = "name"     # "name" | "script" — what Tab/Enter feeds back to the shell

[search]
case_matching = "smart"      # "ignore" | "smart" | "respect"
normalize = true             # unicode normalization
enable_regex = true
substring_matching = true

[ui]
theme = "default"            # see Available Themes below
keybind_mode = "vim"         # currently only "vim" is supported

Available Themes

• default - Classic terminal colors
• gruvbox - Retro groove
• nord - Arctic blue
• dracula - Purple/pink dark theme
• solarized - Precision colors
• catppuccin - Soothing pastels (Mocha)
• tokyonight - Tokyo-inspired dark theme (Storm)
• shades_of_purple - Purple-heavy theme

Keybindings (Vim-style)

The full reference is always available in-app — press ? to toggle the help modal.

Panels & filters

Grouping & sorting

Search

Themes

Actions & quit

Shell Integration

Tab and Enter only affect the parent shell when the alf shell hook is sourced. Add this to your shell config:

# zsh (~/.zshrc)
eval "$(alf activate zsh)"

# bash (~/.bashrc)
eval "$(alf activate bash)"

The hook installs an alf shell function that wraps the binary so selections feed back into the prompt.

Tab vs Enter semantics:

• Tab — populate the prompt with the selected entry; do not run it.
• Enter — run the selected entry immediately (and add it to history).

Development

Requirements

• Rust 1.74.0 or later

Build

cargo build --release

Run tests

cargo test

Run locally

cargo run

Makefile targets

Supported Platforms

• Linux (x86_64, aarch64)
• macOS (Intel, Apple Silicon)
• Windows (x86_64)

License

Licensed under either of the following choices at your option.

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)