alman - Intelligent Alias Manager

A command-line tool and TUI for managing shell aliases with intelligent suggestions based on your command history. Alman helps you organize, create, and manage aliases across multiple files and shells, making your workflow faster and smarter.

🎨 Showcase

Watch alman in action! See how it can transform your command-line workflow with intelligent alias suggestions and intuitive management.

https://github.com/user-attachments/assets/53ae73cf-15ff-4f9e-af31-51ac2b4f3c5e

🚀 Installation

[!IMPORTANT] Shell Configuration Required: After installation, you must add the shell configuration line to your shell config file (check with which $SHELL) or the app will not work. See the Shell Configuration section below for detailed instructions.

Universal Install Script

The easiest way to install alman on any system:

curl -sSfL https://raw.githubusercontent.com/vaibhav-mattoo/alman/main/install.sh | sh

This script will automatically detect your system and install the appropriate binary.

[!NOTE] Remember to add ~/.local/bin to your $PATH if prompted by the install script, by adding export PATH="$HOME/.local/bin:$PATH" in the end of your shell config (~/.bashrc, ~/.zshrc etc).

From Cargo

cargo install alman

From Homebrew (macOS & Linux)

brew tap vaibhav-mattoo/alman
brew install alman

From AUR (Arch Linux)

Using yay:

yay -S alman

Using paru:

paru -S alman

From Source

git clone https://github.com/vaibhav-mattoo/alman.git
cd alman
cargo install --path .

⚙️ Shell Configuration

After installation, you need to configure your shell to use alman. The installer will detect your shell and provide specific instructions, but here are the general steps:

[!NOTE] The installer will automatically detect your shell and show you the exact configuration line to add to your shell config file.

Bash

Add this line to your ~/.bashrc:

eval "$(alman init bash)"

Then reload your configuration:

source ~/.bashrc

Zsh

Add this line to your ~/.zshrc:

eval "$(alman init zsh)"

Then reload your configuration:

source ~/.zshrc

Fish

Add this line to your ~/.config/fish/config.fish:

alman init fish | source

Then reload your configuration:

source ~/.config/fish/config.fish

[!TIP] Alman automatically initializes with your shell history when first run, so you'll have intelligent suggestions right from the start!

📋 Table of Contents

<!-- disabledMarkdownTOC autolink="false" markdown_preview="github" -->

• Showcase
• Installation
  • Universal Install Script
  • From Cargo
  • From Homebrew (macOS & Linux)
  • From AUR (Arch Linux)
  • From Source
• Shell Configuration
  • Bash
  • Zsh
  • Fish
• Quick Start
  • Interactive Mode
  • Command Line Mode
• Interactive Mode
  • Navigation
  • TUI Features
• Command Line Usage
  • Basic Commands
• Usage Examples
  • Basic Usage
  • Advanced Usage
  • Change Command Examples
• Advanced Usage
  • Multi-file Management
  • Suggestion Management
  • Alias Management
• TUI Navigation
  • Key Bindings
  • Features
• Command Line Options
  • Output Options
  • Examples
• Output Format
• Ranking Algorithm
  • Scoring Formula
  • Time-Based Multipliers
  • Factors Explained
• Alias Suggestion Schemes
  • Vowel Removal
  • Abbreviation
  • First Letter Combination
  • Smart Truncation
  • Prefix Matching
• Use Cases
• Uninstallation
• License

<!-- /MarkdownTOC -->

🚀 Quick Start

Interactive Mode

Launch the interactive alias manager:

alman
# or
alman tui

Navigate with arrow keys or jk, select aliases, and manage them interactively.

Command Line Mode

Add, remove, list, and get suggestions for aliases directly from the command line:

# Add an alias
alman add -c "git status" gs

# Remove an alias
alman remove gs

# List all aliases
alman list

# Get alias suggestions
alman get-suggestions -n 10

🖥️ Interactive Mode

The Terminal User Interface (TUI) provides an intuitive way to browse, add, remove, and change aliases:

Navigation

• Arrow keys or jk: Move cursor
• Enter: Select
• a: Add alias
• r: Remove alias
• l: List aliases
• q or Ctrl+C: Quit

TUI Features

• Visual selection: Selected items are highlighted
• Alias suggestions: Get smart suggestions based on your command history
• Multi-file support: Manage aliases across multiple files

💻 Command Line Usage

Basic Commands

# Add a new alias
alman add -c "ls -la" ll

# Remove an alias
alman remove ll

# List all aliases
alman list

# Get intelligent suggestions
alman get-suggestions -n 5

📝 Usage Examples

Basic Usage

# Add a new alias
alman add -c "ls -la" ll

# Remove an alias
alman remove ll

# List all aliases
alman list

# Get intelligent suggestions
alman get-suggestions -n 5

Advanced Usage

# Change an alias name (keeps the same command)
alman change old-alias new-alias

# Delete suggestions for an alias
alman delete-suggestion gs

# Use a specific alias file
alman --alias-file-path ~/.my-aliases add -c "htop" h

[!IMPORTANT] After running alman change old new and sourcing your aliases, only the new alias will work. The old alias will be completely removed from all managed alias files.

🔧 Advanced Usage

Multi-file Management

# Add alias to a specific file
alman --alias-file-path ~/.bash_aliases add -c "ls -lh" lh

# List aliases from a specific file
alman --alias-file-path ~/.zsh_aliases list

Suggestion Management

# Get more suggestions
alman get-suggestions -n 10

# Delete a specific suggestion
alman delete-suggestion gs

🎮 TUI Navigation

The Terminal User Interface provides an intuitive way to manage aliases:

[!TIP] The TUI mode is perfect for browsing your command history and discovering new alias opportunities!

Key Bindings

• Arrow keys or jk: Navigate through aliases
• Enter: Select an alias or action
• a: Add a new alias
• r: Remove selected alias
• l: List all aliases
• q or Ctrl+C: Exit the interface

Features

• Visual feedback: Selected items are highlighted
• Smart suggestions: Get intelligent alias suggestions
• Multi-file support: Manage aliases across different files

⚙️ Command Line Options

Output Options

• -c, --command <COMMAND>: Command to associate with the alias (for add and change)
• -n, --num <N>: Number of suggestions to display (for get-suggestions)
• --alias-file-path <PATH>: Path to the alias file to use

Examples

# Add an alias to a specific file
alman --alias-file-path ~/.bash_aliases add -c "ls -lh" lh

# Get 10 suggestions
alman get-suggestions -n 10

📊 Output Format

Alman displays aliases in a clear, tabular format:

┌─────────┬───────────────┐
│ ALIAS   │ COMMAND       │
├─────────┼───────────────┤
│ gs      │ git status    │
│ ll      │ ls -la        │
└─────────┴───────────────┘

🧠 Ranking Algorithm

Alman uses a sophisticated scoring algorithm to rank commands based on three key factors:

Scoring Formula

Score = Time Multiplier × Length^(3/5) × Frequency

Time-Based Multipliers

• ≤ 1 hour: 4.0× (recent commands get highest priority)
• ≤ 1 day: 2.0× (recent commands)
• ≤ 1 week: 0.5× (older commands)
• > 1 week: 0.25× (very old commands)

Factors Explained

• Recency: Recently used commands score higher, encouraging current workflow patterns
• Frequency: More frequently used commands get higher scores
• Length: Longer commands get slightly higher scores (using length^(3/5) to avoid excessive bias)
• Automatic Reset: When total score exceeds 70,000, all frequencies are reduced by 50% to prevent score inflation

[!TIP] The algorithm automatically adapts to your usage patterns, prioritizing commands you use most frequently and recently!

🎯 Alias Suggestion Schemes

Alman employs multiple intelligent schemes to generate meaningful alias suggestions:

Vowel Removal

Removes vowels to create shorter, memorable aliases:

• git status → gst (removes 'i', 'a', 'u')
• docker ps → dckr ps (r