fsel 3.3.1-kiwicrab

fsel-3.3.1-kiwicrab is not a library.

Logo

(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

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 the Aur
$ paru -S fsel-bin
 # or for git package
$ yay -S fsel-git

# Or Void Linux (Unoffical Repo)
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

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

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-git
# or
$ paru -S fsel-git
```

Or manually:

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

Option 4: 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 (usually pre-installed)
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

Usage

Interactive Mode

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

Features

Advanced Search Ranking: 12-tier prioritization system ensures you find what you're looking for. Pinned apps, exact matches, and prefix matches are intelligently ranked with configurable scoring (frecency, recency, or frequency)
Smart Matching: Searches names, descriptions, keywords, and categories
Smart Ranking: Choose ranking behavior with ranking_mode (frecency, recency, frequency)
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

Navigation

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

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

TTY mode

Launch terminal applications inline in the current terminal session. In TTY mode fsel replaces itself with the selected terminal program (exec),

so the launched app takes over the current terminal (useful for htop, vim, etc.).

Enable with -t or --tty, or set terminal_launcher = "tty" in config. fsel -t fsel --tty

Pre-filled Search Mode

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

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

Dmenu Features

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)

Clipboard History Mode

must have 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

Clipboard Features

Native image previews: Inline and fullscreen (Alt+i) image rendering via ratatui-image — automatic protocol detection (Kitty, Sixel, Halfblocks); no external viewer required
Content Preview: Full text preview panel
Fuzzy Search: Filter clipboard history
Smart Copy: Auto-copies selection to clipboard
Entry Deletion: Press Alt+Delete to delete the selected clipboard entry; the selection remains at the same physical position (the next item becomes selected).
Tag System: Organize clipboard items with tags (requires cclip with tag support)
Requires cclip

Quick Examples

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.

Command Line Options

Usage:
  fsel [OPTIONS]

├─ Core Modes
│  ├─ -p, --program <NAME>         Launch one app immediately and skip the TUI
│  ├─ --cclip                      Browse clipboard history and copy the selected item
│  └─ --dmenu                      Read choices from stdin and print the selection to stdout
│
├─ Startup and Output
│  ├─ -c, --config <FILE>          Read config from FILE before applying CLI overrides
│  ├─ -r, --replace                Replace an existing fsel/cclip instance before starting
│  ├─ -d, --detach                 Start launched GUI apps without keeping this terminal attached
│  ├─ -t, --tty                    Run terminal apps in this TTY and replace the fsel process
│  ├─ -v, --verbose                Print more diagnostics; repeat as -vv or -vvv for more detail
│  ├─ -T, --test                   Enable debug logging, write logs under ~/.config/fsel/logs/, and imply -vvv
│  ├─ --no-exec                    Print the selected item instead of launching it
│  └─ -ss <SEARCH>                 Pre-fill the search box; place this last so it captures the rest
│
├─ Launch Methods
│  ├─ --launch-prefix <CMD>        Prefix launches with a custom command such as 'runapp --'
│  ├─ --systemd-run                Launch through systemd-run --user --scope
│  └─ --uwsm                       Launch through uwsm app --
│
├─ App Launcher Tuning
│  ├─ --clear-history              Delete launch history, then exit
│  ├─ --clear-cache                Delete the desktop entry cache, then exit
│  ├─ --refresh-cache              Rescan desktop entries before showing results
│  ├─ --filter-desktop[=no]        Respect OnlyShowIn/NotShowIn; pass =no to ignore them
│  ├─ --hide-before-typing         Keep the list hidden until you type the first character
│  ├─ --list-executables-in-path   Include executables from $PATH in launcher mode
│  ├─ --match-mode <MODE>          Choose fuzzy or exact matching (default: fuzzy)
│  └─ --prefix-depth <N>           Set how long prefix matches outrank fuzzy matches (default: 3)
│
├─ Dmenu Mode Options
│  ├─ --dmenu0                     Read NUL-separated input instead of newline-separated input
│  ├─ --password[=CHAR]            Mask typed input; optionally choose the mask character
│  ├─ --index                      Print the selected row index instead of the row text
│  ├─ --with-nth <COLS>            Show only these 1-based columns (example: 1,3)
│  ├─ --accept-nth <COLS>          Print only these columns after selection
│  ├─ --match-nth <COLS>           Search only within these columns
│  ├─ --delimiter <CHAR>           Split columns on CHAR instead of spaces
│  ├─ --only-match                 Reject custom text and require a selection from stdin
│  ├─ --exit-if-empty              Quit immediately when stdin provides no items
│  ├─ --select <STRING>            Start with the first matching row preselected
│  ├─ --select-index <N>           Start with row N preselected
│  ├─ --auto-select                Accept automatically when the filtered list reaches one row
│  └─ --prompt-only                Show only the input prompt and hide the list pane
│
├─ Clipboard Mode Options
│  ├─ --tag <NAME>                 Show only clipboard entries tagged NAME
│  ├─ --tag list                   List known tags, then exit
│  ├─ --tag list <NAME>            List clipboard entries carrying NAME, then exit
│  ├─ --tag clear                  Remove stored tag metadata
│  ├─ --tag wipe                   Remove all tags from every clipboard entry
│  └─ --cclip-show-tag-color-names Show tag color names next to tags in cclip mode
│
├─ General
│  ├─ -h                           Show the short summary
│  ├─ -H, --help                   Show this full option tree
│  └─ -V, --version                Print the version and exit
│
└─ Notes
   ├─ Pick only one launch method: --launch-prefix, --systemd-run, or --uwsm
   ├─ --dmenu and --cclip both imply --no-exec
   ├─ --select and --select-index cannot be combined
   └─ Default config path: ~/.config/fsel/config.toml

Launch Methods

Default: Standard execution
Custom Prefix: --launch-prefix="runapp --" or [app_launcher].launch_prefix = ["runapp", "--"]
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)

Verbosity Levels

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

Debug/Test Mode

Use -T or --test to enable detailed debug logging:

# Enable debug mode
fsel -T

# Debug logs are written to ~/.config/fsel/logs/
# Filename format: fsel-debug-YYYYMMDD-HHMMSS-pidXXXXX.log

Debug mode logs:

Startup configuration and loaded data
Query changes (each character typed)
Search snapshots with full scoring breakdown
Selection changes
Launch events
Session timing and statistics

Useful for debugging search ranking, understanding why apps appear in a certain order, or analyzing performance.

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
hide_before_typing = false         # Hide list until you start typing
launch_prefix = ["runapp", "--"]   # Optional command prefix before launched apps
match_mode = "fuzzy"               # "fuzzy" or "exact"
ranking_mode = "frecency"          # "frecency", "recency", or "frequency"
pinned_order = "ranking"           # "ranking", "alphabetical", "oldest_pinned", "newest_pinned"
confirm_first_launch = false       # Confirm before launching new apps with -p
prefix_depth = 3                   # Character depth for prefix matching priority

Advanced Options

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

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

Bug Reports & Feature Requests: Open an issue on GitHub Issues
Pull Requests: Fork the repo, create a feature branch, and submit a PR
Code Style: Run cargo fmt and cargo clippy before submitting
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.