sobriquet

your shell aliases, but better

The Problem

I have quite a few shell aliases, especially for my daily work dealing with a lot of Kubernetes clusters and configurations. Unfortunately, I don't always remember all of them.

I know they're there but always have a typo in them, and it's created a lot of frustration. I'd spend more time trying to recall or correct an alias than actually running the command.

sobriquet solves this.

What is sobriquet?

sobriquet is a blazingly fast fuzzy finder for your shell aliases. It reads your aliases and presents them in a beautiful, full-screen interactive search interface. Just type to search, preview the exact command before executing it, and press Enter to run it.

Think of it like Atuin but for your aliases instead of shell history.

Features

• 🚀 Blazingly Fast - Written in Rust with minimal dependencies, startup time is ~3ms
• 🔍 Full-Screen Search - Beautiful, distraction-free fuzzy finder
• 📊 Frecency Sorting - Smartly sorts aliases by frequency and recency
• 🖥️ Cross-Platform - Works on macOS, Linux, and Windows
• 🐚 Multi-Shell - Supports zsh, bash, and fish
• 🚨 Security Audit - Detect embedded secrets and duplicate aliases
• 💾 Smart Caching - Instant startup with automatic cache invalidation
• 📈 Usage Tracking - See your most-used aliases with built-in stats
• 👁️ Rich Preview - Command breakdown, warnings, source location, and more
• ⚡ Zero Config - Works out of the box, but customizable if you want
• 📚 Shell Integration - Built-in init command for easy setup
• 🔄 Shell Completions - Generate completions for zsh, bash, and fish

Quick Demo

$ sq
┌─ sobriquet ────────────────────────────────────────┐
│ k8s▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁  3/150           │
├──────────────────────────────────────────────────────┤
│ > k8s_prod                                           │
│ > k8s_staging                                        │
│ > k8s_logs                                           │
│                                                      │
│ ────────────────────────────────────────────────────│
│ KUBECONFIG=~/.kube/prod.yaml kubectl               │
│ ────────────────────────────────────────────────────│
│ Command: kubectl                                     │
│ Args: (none)                                         │
│ Source: ~/.zshrc:42                                  │
│ Usage: 157 times (last used 2 hours ago)            │
└──────────────────────────────────────────────────────┘

Start typing to search, press Enter to select.

Installation

From Homebrew

brew tap benjaminch/tap
brew install sobriquet

From AUR (Arch Linux)

yay -S sobriquet
# or
paru -S sobriquet

Or manually:

git clone https://aur.archlinux.org/sobriquet.git
cd sobriquet
makepkg -si

From Cargo (Recommended for other systems)

cargo install sobriquet

This installs sobriquet globally and works on any system with Rust installed.

From Source

git clone https://github.com/benjaminch/sobriquet.git
cd sobriquet
cargo install --path .

From Releases

Download the latest binary for your platform from the Releases page.

macOS

# Apple Silicon
curl -LO https://github.com/benjaminch/sobriquet/releases/latest/download/sobriquet-aarch64-apple-darwin.tar.gz
tar xzf sobriquet-aarch64-apple-darwin.tar.gz
mv sobriquet-aarch64-apple-darwin/sobriquet ~/.local/bin/

# Intel
curl -LO https://github.com/benjaminch/sobriquet/releases/latest/download/sobriquet-x86_64-apple-darwin.tar.gz
tar xzf sobriquet-x86_64-apple-darwin.tar.gz
mv sobriquet-x86_64-apple-darwin/sobriquet ~/.local/bin/

Linux

# x86_64
curl -LO https://github.com/benjaminch/sobriquet/releases/latest/download/sobriquet-x86_64-unknown-linux-musl.tar.gz
tar xzf sobriquet-x86_64-unknown-linux-musl.tar.gz
mv sobriquet-x86_64-unknown-linux-musl/sobriquet ~/.local/bin/

# ARM64
curl -LO https://github.com/benjaminch/sobriquet/releases/latest/download/sobriquet-aarch64-unknown-linux-gnu.tar.gz
tar xzf sobriquet-aarch64-unknown-linux-gnu.tar.gz
mv sobriquet-aarch64-unknown-linux-gnu/sobriquet ~/.local/bin/

Windows

Download sobriquet-x86_64-pc-windows-msvc.zip from the releases page and extract it to a directory in your PATH.

Setup

After installing, set up shell integration. The easiest way is to use the built-in init command:

Zsh

Add this to your ~/.zshrc:

eval "$(sobriquet init zsh)"

Bash

Add this to your ~/.bashrc:

eval "$(sobriquet init bash)"

Fish

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

sobriquet init fish | source

Then restart your shell and you're ready to go!

# Run with Ctrl+S or just type:
sq

Usage

Interactive Search

Just run sobriquet (or sq if you set up the alias):

sq

The full-screen search interface will open. Start typing to search, use arrow keys to navigate, and press Enter to execute.

List All Aliases

sobriquet --list

Or with formatting:

sobriquet --list --format json
sobriquet --list --format json-pretty

Search with a Query

sobriquet --query "git"

This opens the search interface with "git" pre-filled.

View Statistics

sobriquet stats

See your most-used aliases and usage patterns:

# Clear statistics
sobriquet stats clear

Security Audit

sobriquet audit

Scan for potential security issues:

# Check for secrets only
sobriquet audit secrets

# Check for duplicate commands
sobriquet audit duplicates

Generate Completions

# Zsh
sobriquet generate complete-zsh > ~/.zsh/completions/_sobriquet

# Bash
sobriquet generate complete-bash > ~/.local/share/bash-completion/completions/sobriquet

# Fish
sobriquet generate complete-fish > ~/.config/fish/completions/sobriquet.fish

Configuration

sobriquet looks for a config file in these locations (in order of priority):

1. ~/.config/sobriquet/config.toml (recommended, XDG standard)
2. ~/.config/sobriquet.toml
3. ~/.sobriquet.toml

Run sobriquet config to see which config file is being used.

Example Config

[ui]
height = "100%"                # Full screen by default
prompt = "Select alias > "     # Search prompt
preview = true                 # Show rich preview
preview_position = "right"     # Preview position: right, up, down

[shell]
prefer = "zsh"                 # Preferred shell
cache_ttl = 300                # Cache validity in seconds (0 to disable)

[output]
color = "auto"                 # Color mode: auto, always, never

How It Works

1. Collection - sobriquet runs your shell in interactive mode to collect all defined aliases
2. Caching - Aliases are cached for instant startup (~3ms vs ~2s without cache)
3. Search - When you run sobriquet, it launches a full-screen fuzzy finder using skim
4. Preview - As you search, sobriquet shows a rich preview with command breakdown, warnings, and source location
5. Execute - Select an alias and the expanded command is placed on your command line, ready to execute or edit

The key difference from just typing an alias: you see the expanded command before execution, making it impossible to have typos frustrate you.

Performance

sobriquet is carefully optimized to be invisible in your workflow.

Supported Shells

• ✅ zsh
• ✅ bash
• ✅ fish

Security

sobriquet can audit your aliases for:

• Embedded Secrets - API keys, tokens, passwords, AWS credentials, etc.
• Duplicate Commands - Multiple aliases pointing to the same command
• Dangerous Patterns - Risky commands like rm -rf, sudo rm, etc.

All analysis happens locally on your machine. Nothing is sent anywhere.

Why "sobriquet"?

A sobriquet is a nickname or epithet that describes someone or something. Your shell aliases are exactly that—custom nicknames for your commands. The tool helps you remember and use them effectively.

Building from Source

git clone https://github.com/benjaminch/sobriquet.git
cd sobriquet

# Build
cargo build --release

# Run tests
cargo test

# Run clippy
cargo clippy --all-targets

# Install
cargo install --path .

Minimum Supported Rust Version

The minimum supported Rust version is 1.92.0.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using Conventional Commits
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Quality

Please make sure to:

• Run cargo fmt before committing
• Run cargo clippy --all-targets and fix any warnings
• Add tests for new functionality
• Update documentation if needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Atuin - Inspiration for the full-screen search UI
• skim - Fuzzy finder library
• clap - CLI argument parsing
• The open-source community for amazing tools and libraries