(fast select)

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

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

More Info: Detailed Usage Guide

Build Requirements:

• Rust 1.89+ 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
• chafa - for image previews in cclip mode
• Kitty or Sixel-capable terminal - for best image support

Get up and running in 30 seconds:

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

# Or the Aur 
$ yay -S fsel-git
 # or
$ paru -S fsel-git

# Or build from source
git clone https://github.com/Mjoyufull/fsel && cd fsel
cargo build --release
sudo cp target/release/fsel /usr/local/bin/

# Launch it
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.

• 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
  }

• Install from crates.io:

  $ cargo install [email protected]

• To update later:

  $ cargo install [email protected] --force

• Or install latest version (check releases):

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

• Install the git version with your favorite AUR helper:

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

• Or manually:

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

• 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

• uwsm - Universal Wayland Session Manager (for --uwsm flag)
• systemd - For --systemd-run flag (usually pre-installed)
• cclip - Clipboard manager (for --cclip mode)
• chafa - Terminal image viewer (for image previews in cclip mode)
• Kitty terminal - Recommended for best inline image support (Sixel terminals also supported)
• otter-launcher - Pairs nicely with fsel for a complete launcher setup

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

• Smart Matching: Searches names, descriptions, keywords, and categories
• Usage History: Frequently used apps appear higher in results
• Desktop Filtering: Respects OnlyShowIn/NotShowIn fields
• PATH Executables: Optionally show CLI tools from $PATH
• Match Modes: Fuzzy (default) or exact matching
• Pin/Favorite Apps: Press Ctrl-Space to pin apps - they'll always appear first (marked with 📌)
• Custom Keybinds: All keyboard shortcuts are configurable

Keyboard:

• Type to search/filter applications
• ↑/↓ or Ctrl-P/Ctrl-N to navigate up/down
• ←/→ to jump to top/bottom of list
• Enter or Ctrl-Y to launch selected application
• Ctrl-Space to pin/favorite selected app (pinned apps appear first)
• Esc or Ctrl-Q to exit
• Backspace to remove characters from search

Mouse:

• Hover over applications to select them
• Click on an application to launch it
• Scroll wheel to scroll through the application list
• All mouse interactions work alongside keyboard navigation

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 --uwsm -p discord
fsel --systemd-run -vv -p code

Open the TUI with a pre-filled search string. Works with app launcher, dmenu, and cclip modes:

# Open TUI with "firefox" already searched
fsel -ss firefox

# Multi-word search terms work
fsel -ss web browser

# Combine with other options (must be last)
fsel --uwsm -vv -r -ss text editor

# Works with dmenu mode
echo -e "option1\noption2\noption3" | fsel --dmenu -ss opt

# Works with cclip mode
fsel --cclip -ss image

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

Column Operations:

• --with-nth - Display specific columns
• --accept-nth - Output specific columns
• --match-nth - Match against specific columns
• --delimiter - Custom column separator

Input/Output:

• --password - Mask input for passwords
• --index - Output index instead of text
• --dmenu0 - Null-separated input
• --only-match - Force selection from list

Selection:

• --select - Pre-select by string
• --select-index - Pre-select by index
• --auto-select - Auto-select single match

Modes:

• --prompt-only - Text input without list
• --match-mode=exact - Exact matching only
• Drop-in dmenu replacement (symlink as dmenu)

• must have cclip

Browse and select from your clipboard history with image previews:

# Browse clipboard history with cclip integration
fsel --cclip

• Image Previews: Inline rendering (Kitty/Sixel terminals)
• Content Preview: Full text preview panel
• Fuzzy Search: Filter clipboard history
• Smart Copy: Auto-copies selection to clipboard
• Requires cclip

Dmenu mode:

# Simple selection
echo -e "Edit\nView\nDelete" | fsel --dmenu

# Password input
echo -e "pass1\npass2" | fsel --dmenu --password

# Process killer
ps aux | fsel --dmenu --with-nth 2,11 --accept-nth 2 | xargs kill

# Git branch switcher
git branch | fsel --dmenu --select main | xargs git checkout

# Drop-in dmenu replacement
ln -s $(which fsel) ~/.local/bin/dmenu

Scripting:

# SSH picker
grep "^Host " ~/.ssh/config | fsel --dmenu --with-nth 2 | xargs ssh

# File opener
find . -type f | fsel --dmenu | xargs xdg-open

# Window switcher (Sway)
swaymsg -t get_tree | jq -r '..|select(.name)|.name' | fsel --dmenu

See USAGE.md for more examples and advanced usage.

Usage: fsel [options]

Core Modes:
  -p, --program <name>   Launch program directly (bypass TUI)
      --cclip            Clipboard history mode
      --dmenu            Dmenu-compatible mode

Control Flags:
  -r, --replace          Replace running fsel or cclip instance
  -d, --detach           Detach launched applications (works with uwsm/systemd-run)
  -v, --verbose          Increase verbosity (repeatable)
      --systemd-run      Launch via systemd-run --user --scope
      --uwsm             Launch via uwsm app
      --no-exec          Print selected command instead of launching
  -ss <search>           Pre-fill search (must be last option)

Quick Extras:
      --clear-history    Clear launch history database
      --clear-cache      Clear cached desktop entries
      --refresh-cache    Refresh desktop file list
      --filter-desktop[=no] Respect OnlyShowIn/NotShowIn (default: yes)
      --list-executables-in-path Include executables from $PATH
      --hide-before-typing Hide list until input typed
      --match-mode <mode> fuzzy | exact (default: fuzzy)

Help:
  -H, --help             Show detailed option tree (same as `fsel -H`)
  -h                     Show concise overview
  -V, --version          Show version number and exit

Run `fsel -H` or `fsel --help` to see the full tree-style reference covering every dmenu and clipboard flag.

• Default: Standard execution
• Sway Integration: Automatically enabled when $SWAYSOCK is set. Uses swaymsg exec to launch applications in the current workspace (requires Sway)
• systemd-run: --systemd-run launches applications in isolated systemd user scopes (requires systemd)
• uwsm: --uwsm launches applications through the Universal Wayland Session Manager (requires uwsm to be installed)

• -v: Show application execution details
• -vv: Show application paths and additional metadata
• -vvv: Show debug information including usage statistics

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

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

# App launcher
terminal_launcher = "alacritty -e"

[app_launcher]
filter_desktop = true              # Filter apps by desktop environment
list_executables_in_path = false   # Show CLI tools from $PATH
hide_before_typing = false         # Hide list until you start typing
match_mode = "fuzzy"               # "fuzzy" or "exact"
confirm_first_launch = false       # Confirm before launching new apps with -p

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

# UI customization
rounded_borders = true
main_border_color = "White"
apps_border_color = "White"
input_border_color = "White"

# Layout (percentages)
title_panel_height_percent = 30    # Top panel height (10-70%)
input_panel_height = 3             # Input panel height in lines
title_panel_position = "top"       # "top", "middle", or "bottom"

# Dmenu mode
[dmenu]
password_character = "*"
exit_if_empty = false

# Clipboard mode
[cclip]
image_preview = true
hide_inline_image_message = false

# Custom keybinds (optional)
[keybinds]
up = ["up", { key = "k", modifiers = "ctrl" }]
down = ["down", { key = "j", modifiers = "ctrl" }]
select = ["enter"]
exit = ["esc", { key = "q", modifiers = "ctrl" }]
pin = [{ key = "space", modifiers = "ctrl" }]

See config.toml and keybinds.toml for all options with detailed comments.

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 = float, ^(launcher)$
windowrule = size 500 430, ^(launcher)$

dwm/bspwm/any WM:

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

Feature requests and bug reports are welcome.

Pull requests for bug fixes or requested features are accepted.

Please use GitHub issues and pull requests for contributions.

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.

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 Kitty (best) or Sixel-capable terminal (Foot, WezTerm, etc.)
• Install chafa for image rendering
• Check image_preview = true in config
• Images automatically render inside content panel borders

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"

Fork of gyr by Namkhai B.

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