Mjoyufull/fsel: Fast TUI app launcher for GNU/Linux and *BSD. Contribute to Mjoyufull/fsel development by creating a

github.com · 2026-08-21 · by Long Nguyen ·github
Fast TUI app launcher for GNU/Linux and *BSD. Contribute to Mjoyufull/fsel development by creating an account on GitHub.

Mjoyufull/fsel

Fast TUI app launcher for GNU/Linux and *BSD. Contribute to Mjoyufull/fsel development by creating an account on GitHub.

398 stars · 11 forks

README

(fast select)

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

Table of Contents

Requirements Quickstart Documentation Install Usage Configuration

Environment variable overrides

Contributing Troubleshooting License

Start Here: Detailed Usage Guide Requirements Build Requirements:

Rust 1.94+ 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.7.0-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 (Latest Release)

Build and install via Cargo: $ cargo install fsel@3.7.0-kiwicrab

To update later: $ cargo install fsel@3.7.0-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-bin $ 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 Reversible Hiding: Press Alt-Delete to hide one exact launcher source and Alt-U to undo Optional Deduplication: Enable deterministic XDG-aware duplicate suppression when wanted Match Modes: Fuzzy (default) or exact matching

See USAGE.md - App Launcher for TTY mode, launch prefixes, --detach, cache management, --replace, and more. Hidden entries are stored in fsel's database; their .desktop files and executables are not changed. Manage persistent hides without opening the TUI: fsel --list-hidden fsel --unhide 12 fsel --unhide-all Set auto_hide_duplicates = true under [app_launcher] to suppress entries with the same desktop-file ID or normalized visible name. It defaults to false; manual hiding always targets one exact source path, including duplicate entries in the same directory or across Bedrock strata. Direct Launch Mode Launch applications directly from the command line without opening the TUI:

Launch Firefox directly

fsel -p firefox

Launch the best fuzzy match for "terminal" (default match mode)

fsel -p terminal

Partial names work while match_mode is fuzzy

fsel -p fire # Finds Firefox

Exact mode requires an exact app or executable name

fsel --match-mode=exact -p firefox fsel --match-mode=exact -p fire # Fails: no exact match

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, environment variables, 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 filter_actions = false # Keep desktop actions visible; set true to hide them auto_hide_duplicates = false # Opt in to deterministic duplicate suppression 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. [app_launcher].match_mode = "exact" also applies to -p/--program, where it requires an exact app or executable name. Environment variable overrides After the config file is loaded, any FSEL_* variable set in the process environment overrides the corresponding setting. Use this for one-off launches, wrappers, or systemd units without editing config.toml.

Root / shared keys: FSEL_ plus the uppercase TOML key (e.g. match_mode → FSEL_MATCH_MODE). Section keys: FSEL_DMENU_*, FSEL_CCLIP_*, and FSEL_APP_LAUNCHER_* mirror [dmenu], [cclip], and [app_launcher] fields.

FSEL_MATCH_MODE=exact fsel FSEL_APP_LAUNCHER_FILTER_ACTIONS=true fsel FSEL_HIGHLIGHT_COLOR=Cyan FSEL_DMENU_DELIMITER=: fsel --dmenu < items.txt man fsel summarizes this under ENVIRONMENT. For the full variable list, see Environment variables in USAGE.md. 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

Too many desktop action entries?

Use --filter-actions to hide desktop actions like "New Window" Or set filter_actions = true under [app_launcher]

Hidden the wrong launcher entry?

Press Alt-U before leaving the launcher to restore the most recent hide Run fsel --list-hidden, then fsel --unhide <ID> to restore a specific entry Run fsel --unhide-all to clear every manual hide

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

source

github.com · 5 images · 130 links

Comments (0)

No comments yet