sobriquet

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
• 🔒 Safe Preview - Commands shown without expansion by default (no accidental execution)
• 💾 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
• 🔄 Dynamic Toggle - Expand variables and command substitutions on-demand with Ctrl+X
• ⚡ 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
• 💡 Alias Tips - Get reminded when you type full commands instead of using your aliases

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 install benjaminch/sobriquet/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.

Keybindings:

• Enter - Execute the selected alias
• Ctrl+X - Toggle secret masking (show/hide sensitive values like tokens, API keys)
• Ctrl+C / Esc - Exit without executing

Security Note: By default, sensitive values (tokens, API keys, secrets) are automatically masked in both the list and preview. Press Ctrl+X to reveal the full command.

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

Alias Tips

sobriquet can remind you when you type full commands instead of using your aliases (inspired by alias-tips):

$ git status
💡 Alias tip: gst

To enable tips, set the environment variable in your shell config:

# In ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
export SOBRIQUET_TIPS_ENABLE=1

Or configure it in your config.toml:

[tip]
enable = true

The tips feature integrates with your shell's preexec hook to check each command you type and suggest matching aliases.

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
preview_expand_details = false # Expand variables and show command details (default: false)
                               # When false: Shows raw commands (secure, no expansion)
                               # When true: Expands $HOME, $(commands), etc.
                               # Tip: Toggle on-the-fly with Ctrl+X

[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. Install git hooks: ./scripts/install-hooks.sh
4. Make your changes
5. Commit your changes using Conventional Commits
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Setup

After cloning the repository, install the git hooks to ensure code quality:

./scripts/install-hooks.sh

This installs a pre-commit hook that automatically runs:

• cargo fmt --check - Ensures code is properly formatted
• cargo clippy - Catches common mistakes and enforces best practices

If you need to bypass the hooks temporarily (not recommended), use:

git commit --no-verify

For detailed development instructions, see DEVELOPMENT.md.

Code Quality

Please make sure to:

• Run cargo fmt before committing (automated by pre-commit hook)
• Run cargo clippy --all-targets and fix any warnings (automated by pre-commit hook)
• Add tests for new functionality
• Update documentation if needed

For coding standards and best practices, see CODING_PRACTICES.md.

Releasing (Maintainers)

Releasing a new version is fully automated:

# One command to create and publish a release
make release VERSION=0.3.0

This will:

• Update Cargo.toml and Cargo.lock
• Run tests
• Create commit and tag
• Push to GitHub
• Automatically trigger CI to build binaries, publish to crates.io, and update Homebrew

License

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

Acknowledgments

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