(fast select)

Fast TUI app launcher and fuzzy finder for GNU/Linux and *BSD

Table of Contents

• Requirements
• Quickstart
• Documentation
• Install
• Usage
• Configuration
• Contributing
• Troubleshooting
• License

Start Here: Detailed Usage Guide

Requirements

Build Requirements:

• Rust 1.90+ stable (NOT nightly)
  • Install: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Verify: rustc --version (should show stable, not nightly)
  • If using nightly: rustup default stable
• Cargo (comes with Rust)

Runtime Requirements:

• GNU/Linux or *BSD
• Terminal emulator

Optional:

• cclip - for clipboard history mode
• Kitty, Sixel-, or Halfblocks-capable terminal - for native inline image previews in cclip mode (see ratatui-image)

Note: Image previews in cclip mode use built-in ratatui-image (no external viewer). Versions before 3.1.0 required chafa for image previews; 3.1.0 and later do not.

Quickstart

Get up and running in 30 seconds:

# Install with Nix (recommended)
nix run github:Mjoyufull/fsel

# Or install from Cargo
cargo install fsel@3.3.1-kiwicrab

# Launch fsel
fsel

# Use as dmenu replacement
echo -e "Option 1\nOption 2\nOption 3" | fsel --dmenu

# Browse clipboard history (requires cclip)
fsel --cclip

That's it. Type to search, arrow keys to navigate, Enter to launch.

Need install variants, launch methods, or mode-specific examples? See USAGE.md.

Install

Option 1: Nix Flake (Recommended)

• Build and run with Nix flakes:

  $ nix run github:Mjoyufull/fsel

• Add to your profile:

  $ nix profile add github:Mjoyufull/fsel

• Add to your flake.nix inputs:

  {
    inputs.fsel.url = "github:Mjoyufull/fsel";
    # ... rest of your flake
  }

Option 2: Cargo

• Install from crates.io:

  $ cargo install fsel@3.3.1-kiwicrab

• To update later:

  $ cargo install fsel@3.3.1-kiwicrab --force

• Or install latest version (check releases):

  $ cargo search fsel  # See available versions
  $ cargo install fsel@<version>

Option 3: AUR (Arch Linux)

• Install the git version with your favorite AUR helper:

  $ yay -S fsel-bin
  # or
  $ paru -S fsel-git

• Or manually:

  $ git clone https://aur.archlinux.org/fsel-bin.git
  $ cd fsel-bi
  $ makepkg -si

Option 4: Void linux (Unoffical Repo)

• Install fsel on void

  echo repository=https://raw.githubusercontent.com/Event-Horizon-VL/blackhole-vl/repository-x86_64 | sudo tee /etc/xbps.d/20-repository-extra.conf
  sudo xbps-install -S fsel

Option 5: Build from source

• Install Rust stable
• Build:

  $ git clone https://github.com/Mjoyufull/fsel && cd fsel
  $ cargo build --release

• Copy target/release/fsel to somewhere in your $PATH
• (Optional) Create a dmenu symlink for drop-in compatibility:

  $ ./create_dmenu_symlink.sh

  Or manually: ln -s $(which fsel) ~/.local/bin/dmenu

Optional Dependencies

• uwsm - Universal Wayland Session Manager (for --uwsm flag)
• systemd - For --systemd-run flag
• cclip - Clipboard manager (for --cclip mode)
• Kitty, Foot, WezTerm, or other Sixel/Kitty/Halfblocks-capable terminal - For native inline image previews in cclip mode (powered by ratatui-image; no chafa needed in 3.1.0+)
• otter-launcher - Pairs nicely with fsel for a complete launcher setup see Usage

Usage

Interactive Mode

Run fsel from a terminal to open the interactive TUI launcher.

# Launch fsel
fsel

# Pre-fill search (must be last)
fsel -ss firefox

# Direct launch (no UI)
fsel -p firefox

Highlights:

• Advanced Search Ranking: Configurable scoring with frecency, recency, or frequency
• Smart Matching: Searches names, descriptions, keywords, and categories
• Pin/Favorite Apps: Press Ctrl-Space to pin apps - pinned apps always appear first
• Match Modes: Fuzzy (default) or exact matching

See USAGE.md - App Launcher for TTY mode, launch prefixes, --detach, cache management, --replace, and more.

Direct Launch Mode

Launch applications directly from the command line without opening the TUI:

# Launch Firefox directly
fsel -p firefox

# Launch first match for "terminal"
fsel -p terminal

# Works with partial names
fsel -p fire  # Finds Firefox

# Combine with launch options
fsel --launch-prefix="runapp --" -p discord
fsel --uwsm -p discord
fsel --systemd-run -vv -p code

Dmenu Mode

Fsel includes a full dmenu replacement mode that reads from stdin and outputs selections to stdout:

# Basic dmenu replacement
echo -e "Option 1\nOption 2\nOption 3" | fsel --dmenu

# Display only specific columns (like cut)
ps aux | fsel --dmenu --with-nth 2,11  # Show only PID and command

# Use custom delimiter
echo "foo:bar:baz" | fsel --dmenu --delimiter ":"

# Pipe from any command
ls -la | fsel --dmenu
find . -name "*.rs" | fsel --dmenu
git log --oneline | fsel --dmenu

See USAGE.md - Dmenu Mode for column operations, password input, pre-selection, exact matching, --dmenu0, and prompt-only mode.

Clipboard History Mode

Requires cclip.

Browse and select from your clipboard history with image previews:

# Browse clipboard history with cclip integration
fsel --cclip

# Filter by tag
fsel --cclip --tag prompt

# List all tags
fsel --cclip --tag list

# List items with specific tag (verbose shows details)
fsel --cclip --tag list prompt -vv

# Clear tag metadata from fsel database
fsel --cclip --tag clear

# Show tag color names in display
fsel --cclip --cclip-show-tag-color-names

See USAGE.md - Clipboard Mode for tag management, keybindings, inline image details, and more clipboard-specific behavior.

Command Line Help

# Quick overview grouped by mode/flags
fsel -h

# Full tree-style reference covering every option
fsel -H

# Show verbose output
fsel -vvv

See USAGE.md for more examples, launch methods, scripting recipes, debugging notes, and advanced usage.

Configuration

Config file: ~/.config/fsel/config.toml

Basic Setup

# Colors
highlight_color = "LightBlue"
cursor = "█"

# App launcher
terminal_launcher = "alacritty -e"

# Pin/favorite settings (root-level UI options)
pin_color = "rgb(255,165,0)"       # Color for pin icon (orange)
pin_icon = "📌"                     # Icon for pinned apps

[app_launcher]
filter_desktop = true              # Filter apps by desktop environment
list_executables_in_path = false   # Show CLI tools from $PATH
match_mode = "fuzzy"               # "fuzzy" or "exact"
ranking_mode = "frecency"          # "frecency", "recency", or "frequency"
pinned_order = "ranking"           # "ranking", "alphabetical", "oldest_pinned", "newest_pinned"

Field placement matters. Root-level UI options and [app_launcher] / [dmenu] / [cclip] sections are validated separately. See config.toml and keybinds.toml for all options with detailed comments.

Window Manager Integration

Sway/i3:

# ~/.config/sway/config
set $menu alacritty --title launcher -e fsel
bindsym $mod+d exec $menu
for_window [title="^launcher$"] floating enable, resize set width 500 height 430, border none

# Clipboard history
bindsym $mod+v exec 'alacritty --title clipboard -e fsel --cclip'

Hyprland:

# ~/.config/hypr/hyprland.conf
bind = $mod, D, exec, alacritty --title launcher -e fsel
windowrule {
    match:title = launcher
    float = on 
    center = on 
    size = 500 430
}

Niri:

# ~/.config/niri/config.kdl
window-rule {
    match title="launcher"
    open-floating true
}

# Add inside binds { ... }
Mod+D { spawn "alacritty" "--title" "launcher" "-e" "fsel"; }

dwm/bspwm/any WM:

# Use dmenu mode
bindsym $mod+d exec "fsel --dmenu | xargs swaymsg exec --"

Contributing

Contributions are welcome! Whether you're reporting bugs, suggesting features, or submitting code, we appreciate your help making fsel better.

How to Contribute

1. Bug Reports & Feature Requests: Open an issue on GitHub Issues
2. Pull Requests: Fork the repo, create a feature branch, and submit a PR
3. Code Style: Run cargo fmt and cargo clippy before submitting
4. Testing: Ensure cargo test and cargo build --release pass

Development Workflow

See CONTRIBUTING.md for detailed guidelines on:

• Branch naming conventions
• Commit message format
• Pull request process
• Code review standards
• Release procedures

All contributors are valued and appreciated. Your name will be added to the contributors list, and significant contributions will be highlighted in release notes.

Thank you for helping improve fsel!

Philosophy

fsel is a unified TUI workflow tool built for terminal-centric setups. It combines app launching, dmenu functionality, and clipboard history into one scriptable interface with consistent keybinds and theming.

This means:

• It's built for my workflow first, but PRs for bug fixes and useful features are welcome as long as they fit in scope.
• Older versions and the original gyr exist if you want something more minimal.

---

Troubleshooting

Apps not showing up?

• Check $XDG_DATA_DIRS includes /usr/share/applications
• Try --filter-desktop=no to disable desktop filtering
• Use -vvv for debug info

Mouse not working?

• Check your terminal supports mouse input
• Try disable_mouse = false in config

Images not showing in cclip mode?

• Use a Kitty-, Sixel-, or Halfblocks-capable terminal (e.g. Kitty, Foot, WezTerm). Image preview uses built-in ratatui-image; no chafa or other external viewer is needed (3.1.0+).
• Check image_preview = true in config
• Images render inside the content panel; press Alt+i for fullscreen preview

Fuzzy matching too loose?

• Try --match-mode=exact for stricter matching
• Or set match_mode = "exact" in config

Terminal apps not launching?

• Set terminal_launcher in config
• Example: terminal_launcher = "kitty -e"

Credits

Fork of gyr by Namkhai B.

License

BSD 2-Clause (c) 2020-2022 Namkhai B., Mjoyufull