FSEL(1)

📦
version 3.6.0 · 2 versions
, in nixpkgs unstable

💅 FSEL — like, the manual bestie

So you opened FSEL(1) from the User Commands section, and honestly? You're about to have a good time, because fsel is that girl. Let's get into it.

🦋 NAME

fsel — a fast TUI app launcher and fuzzy finder for GNU/Linux and *BSD. Yes, both. She's versatile. 💅

✨ SYNOPSIS ✨

fsel [OPTIONS]

That's it. That's the whole vibe. No subcommands, no drama, just options.

💖 DESCRIPTION 💖

Okay so picture this: fsel is a terminal-based application launcher with advanced fuzzy search, dmenu compatibility, and clipboard history integration all up in there. She scans XDG desktop entries — and, if you want, PATH executables too — giving you a genuinely fast interface for launching applications. Iconic behavior, truly.

She features a sophisticated 12-tier search ranking system with configurable prioritization (that's frecency, recency, or frequency, bestie). The ranking system prioritizes pinned apps, exact matches, prefix matches, and word-start matches, and you get configurable prefix depth for fine-tuning that search behavior. And you can pin your faves with Ctrl+Space for instant access. Main character energy fr fr. 👑

✨ OPTIONS ✨

🎀 App Launcher Options 🎀

  • -c, --config CONFIG — Pick a specific config file. (default: ~/.config/fsel/config.toml)
  • -r, --replace — Replace existing fsel or cclip instances. She terminates lingering processes before reopening the database, so no ghost processes haunting you.
  • --clear-history — Clear the launch history database. Fresh start, new you. 🫶
  • --clear-cache — Clear the desktop file cache.
  • --refresh-cache — Force a refresh of the desktop file list (aka rescan for new apps).
  • --list-hidden — List manually hidden launcher entries and their numeric IDs, then exit.
  • --unhide ID — Restore one manually hidden launcher entry by numeric ID, then exit.
  • --unhide-all — Restore every manually hidden launcher entry, then exit. Un-hide everybody, she's being generous.
  • -p, --program NAME — Launch a program directly, bypassing the TUI entirely. Respects --match-mode; exact mode requires an exact app or executable name, no shortcuts.
  • -ss SEARCH — Pre-fill the search in the TUI. Works with app launcher, dmenu, and cclip modes. ⚠️ Must be the last option — like, actually last, don't be sneaky.
  • -v, --verbose — Increase verbosity level, and you can stack it: -v, -vv, -vvv. Go off.
  • --no-exec — Print the selected application to stdout instead of launching it. For the observational girlies.
  • --launch-prefix CMD — Launch applications through a custom command prefix (example: runapp --).
  • --systemd-run — Launch applications using systemd-run --user --scope. Pairs with -d/--detach.
  • --uwsm — Launch applications using uwsm app. Pairs with -d/--detach.
  • --filter-desktop[=no] — Filter apps by OnlyShowIn/NotShowIn fields. (default: yes)
  • --filter-actions[=no] — Hide desktop action entries such as "New Window" and "Open Private Window". (default: no)
  • --auto-hide-duplicates[=no] — Suppress equal desktop-file IDs and normalized visible names using XDG application-directory precedence. (default: no) Note: automatic exclusions are not persisted, so don't expect them to stick around.
  • --list-executables-in-path — Include executables from $PATH alongside desktop apps. Two worlds colliding, slay.
  • --hide-before-typing — Hide the list until you type your first character. Mysterious. 🦋
  • --match-mode MODE — Match mode: 'fuzzy' or 'exact'. (default: fuzzy)
  • --prefix-depth N — Character depth for prefix matching priority. (default: 3) When the query length is within this depth, prefix matches (exact, word-start) are prioritized over fuzzy matches.
  • -T, --test — Enable debug/test mode with detailed logging. Logs get written to ~/.config/fsel/logs/ with timestamped filenames (fsel-debug-YYYYMMDD-HHMMSS-pidXXXXX.log). The logs include startup configuration, query changes, search snapshots with scoring breakdown, selection changes, launch events, and session statistics. Genuinely useful for debugging search ranking and analyzing performance, ngl.
  • -d, --detach — Detach launched applications from the terminal session. Compatible with --launch-prefix, --systemd-run, and --uwsm.
  • -t, --tty — Launch terminal apps in the current terminal (TTY mode). This replaces the fsel process with the launched app, so use it with -p/--program. Overrides terminal_launcher. Super useful for TTY login sessions. 💀

🌸 Dmenu Mode Options 🌸

  • --dmenu — Dmenu mode: read from stdin, output the selection to stdout.
  • --dmenu0 — Like --dmenu but with null-separated input.
  • --password[=CHAR] — Password mode: masks the input. (default char: *)
  • --index — Output the index instead of the text.
  • --with-nth COLS — Display only specified columns (comma-separated, e.g., 1,3).
  • --accept-nth COLS — Output only specified columns.
  • --match-nth COLS — Match against only specified columns.
  • --delimiter CHAR — Column delimiter. (default: space)
  • --only-match — Don't allow custom input, only return selected items. Strict queen.
  • --exit-if-empty — Exit immediately if stdin is empty. No empty air, we leave.
  • --select STRING — Pre-select the first matching entry.
  • --select-index N — Pre-select the entry at index n.
  • --auto-select — Auto-select when only one match remains.
  • --prompt-only — Prompt-only mode: no list, just the input.

🎀 Clipboard Mode Options 🎀

  • --cclip — Clipboard history mode: browse cclip history with inline and fullscreen image previews (requires cclip). Image preview uses built-in terminal graphics (Kitty/Sixel/Halfblocks), so no external viewer is required. Obsessed. 😭
  • --tag NAME — Filter clipboard items by tag (use with --cclip).
  • --tag list — List all tags (use with --cclip).
  • --tag list NAME — List items with a specific tag (use with --cclip).
  • --tag clear — Clear tag metadata from the fsel database (colors, emojis). Note: this does not remove tags from cclip entries.
  • --tag wipe — Wipe ALL tags from cclip entries (requires cclip 3.2+). This one actually removes the tag text from the real clipboard items, so be sure that's what you want.
  • --cclip-show-tag-color-names — Show tag color names in the clipboard item display (use with --cclip).

🌈 General Options 🌈

  • -h — Show a concise help overview.
  • -H, --help — Show the detailed tree-style help covering all the modes.
  • -T, --test — Enable debug/test mode with detailed logging. See the App Launcher Options section above for the full description.
  • -V, --version — Show the version number.
  • -t, --tty — Launch in the current terminal (TTY mode). See App Launcher Options.

🧚 CONFIGURATION 🧚

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

Example configuration — copy this energy:

# Root level - Colors and UI options
highlight_color = "LightBlue"
cursor = "█"
terminal_launcher = "kitty -e"  # Use "tty" for TTY mode (same as -t flag)
rounded_borders = true
hard_stop = false

# Border colors
main_border_color = "White"
apps_border_color = "White"
input_border_color = "White"

# Layout
title_panel_height_percent = 30
input_panel_height = 3
title_panel_position = "top"  # or "middle" or "bottom"

# Pin system
pin_icon = "📌"
pin_color = "rgb(255,165,0)"

# App launcher specific options (must be in section)
[app_launcher]
filter_desktop = true
filter_actions = false
auto_hide_duplicates = false
list_executables_in_path = false
hide_before_typing = false
match_mode = "fuzzy"
ranking_mode = "frecency"
pinned_order = "ranking"
confirm_first_launch = false
prefix_depth = 3

# Dmenu mode overrides (optional)
[dmenu]
delimiter = " "
show_line_numbers = true

# Clipboard mode overrides (optional)
[cclip]
image_preview = true
hide_inline_image_message = false

# Custom keybinds (optional)
[keybinds]
up = ["up", { key = "p", modifiers = "ctrl" }]
down = ["down", { key = "n", modifiers = "ctrl" }]
select = ["enter"]
exit = ["esc", { key = "q", modifiers = "ctrl" }]
pin = [{ key = "space", modifiers = "ctrl" }]
hide = [{ key = "delete", modifiers = "alt" }]
unhide_last = [{ key = "u", modifiers = "alt" }]

See the example config.toml and keybinds.toml for all available options. 💜

🦋 KEYBOARD SHORTCUTS 🦋

  • ↑/↓ or Ctrl+P/Ctrl+N — Navigate up/down.
  • ←/→ — Jump to the top/bottom of the list.
  • Enter or Ctrl+Y — Launch the selected application.
  • Ctrl+Space — Toggle pin/favorite for the selected app (pinned apps always appear first 💅).
  • Alt+Delete — Hide the exact selected launcher entry without deleting or editing its source file. No file violence here.
  • Alt+U — Restore the most recently hidden launcher entry.
  • Esc or Ctrl+Q or Ctrl+C — Exit.
  • Backspace — Remove characters from the search.
  • Tab/Shift+Tab — Navigate down/up (the alternative route).
  • Home/End — Jump to the first/last item.

🩰 Clipboard Mode Keybinds 🩰

  • Alt+i — Open a fullscreen image preview for the selected clipboard item (native TUI; press Esc or q to return).
  • Ctrl+T — Tag the selected clipboard item.
  • Alt+Delete — Delete the selected clipboard item (runs cclip delete). Your selection and scroll position are preserved after deletion, which is such a nice touch.

🐭 Mouse Support 🐭

  • Hover — Select an application.
  • Click — Launch an application.
  • Scroll — Navigate the list (selection follows mouse position).

All keybinds can be customized via ~/.config/fsel/keybinds.toml or in the [keybinds] section of config.toml. And when both are present? The [keybinds] section in config.toml takes precedence. Precedence, periodt. 👑

🔥 LAUNCH METHODS 🔥

  • Default — Standard execution. Simple, clean, no notes.
  • Custom Prefix — Launch applications through a custom prefix with --launch-prefix or [app_launcher].launch_prefix.
  • systemd-run — Launch applications in isolated systemd user scopes with the --systemd-run flag.
  • uwsm — Launch applications through Universal Wayland Session Manager with the --uwsm flag.
  • Detach — Use -d/--detach to prevent apps from being killed when the terminal closes. Works standalone or combined with --launch-prefix, --systemd-run, or --uwsm.

okay that's the part 1 of it bestie, there's literally more coming so don't go anywhere 🫶✨

✨ EXAMPLES ✨

Okay bestie, this is the fun part — actual things you can type. Copy-paste energy only, no cap. 💅

Basic Usage

Launch fsel interactively, like the main character it is:

fsel

Direct Launch

Launch Firefox directly without the TUI — boom, straight to business:

fsel -p firefox

Launch the best fuzzy match for "terminal":

fsel -p term

Require an exact app or executable name for direct launch — no fuzzy wiggle room, periodt:

fsel --match-mode=exact -p firefox

Hide desktop action entries in launcher mode:

fsel --filter-actions

Suppress duplicate launcher entries for one invocation:

fsel --auto-hide-duplicates

Launch with detach for GUI apps — very “I have places to be” of you:

fsel --detach -p discord
fsel --launch-prefix "runapp --" -p discord
fsel --systemd-run -p code

Open the TUI with "firefox" already searched — she’s ready before you are:

fsel -ss firefox

Multi-word search, and yes, this must be last option — don’t test her:

fsel --uwsm -vv -r -ss text editor

Pre-fill search in dmenu mode:

echo -e "firefox\nchrome\nfirefox-dev" | fsel --dmenu -ss fire

Pre-fill search in cclip mode:

fsel --cclip -ss image

Dmenu Mode

Basic dmenu replacement — iconic behavior:

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

Process killer — choose your victim, then xargs kill does the rest 😭:

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

Git branch switcher — because typing branch names is so last season:

git branch | fsel --dmenu --select main | xargs git checkout

SSH connection picker — your ~/.ssh/config but make it cute:

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

Window switcher for Sway — jq girlies rise:

swaymsg -t get_tree | jq -r '..|select(.name)|.name' | fsel --dmenu

Clipboard History

Browse clipboard history — requires cclip, so make sure she’s installed:

fsel --cclip

Filter by tag — prompt and code are giving organized:

fsel --cclip --tag prompt
fsel --cclip --tag code

List all tags:

fsel --cclip --tag list

List items with a specific tag, verbose style:

fsel --cclip --tag list prompt -vv

Clear fsel tag metadata:

fsel --cclip --tag clear

Wipe ALL tags from cclip entries — highkey dramatic, use with intention:

fsel --cclip --tag wipe

🌸 ENVIRONMENT 🌸

These are the little environment gremlins that tell fsel where stuff lives and what vibe we’re in. 🧚

  • XDG_CONFIG_HOME — user config directory (default: ~/.config)
  • XDG_DATA_HOME — user data directory (default: ~/.local/share)
  • XDG_DATA_DIRS — system data directories (default: /usr/local/share:/usr/share)
  • XDG_CURRENT_DESKTOP — used for desktop environment filtering (OnlyShowIn/NotShowIn)
  • WAYLAND_DISPLAY — used to detect Wayland vs X11 for clipboard operations
  • FSEL_* — environment variables with the FSEL_ prefix override config file settings
  • FSEL_APP_LAUNCHER_FILTER_ACTIONS — set to true to hide desktop action entries in app launcher mode, or false to keep them visible
  • FSEL_APP_LAUNCHER_AUTO_HIDE_DUPLICATES — set to true to enable deterministic duplicate suppression in app launcher mode (default: false)

🎀 FILES 🎀

Here’s where fsel keeps her stuff. Do not reorganize her room without asking. 💖

  • ~/.config/fsel/config.toml — user configuration file
  • ~/.config/fsel/keybinds.toml — keybind customization file (optional, can use [keybinds] in config.toml)
  • ~/.local/share/fsel/hist_db.redb — launch history, frecency data, pinned apps, and manually hidden entries database (redb format)
  • ~/.local/share/fsel/fsel-fsel.lock — lock file for single instance (app launcher mode)
  • ~/.cache/fsel/fsel-cclip.lock — lock file for single instance (cclip mode)
  • ~/.config/fsel/logs/fsel-debug-*.log — debug log files (created when using -T/--test flag)
  • /usr/share/applications/*.desktop — system desktop entries
  • ~/.local/share/applications/*.desktop — user desktop entries

💀 EXIT STATUS 💀

Short and iconic:

  • 0 — Success
  • 1 — Error occurred

🐛 BUGS 🐛

Found a bug? Don’t suffer in silence, bestie — report it here:

https://github.com/Mjoyufull/fsel/issues

👑 AUTHOR 👑

Mjoyufull <https://github.com/Mjoyufull>

Original gyr by Namkhai B.

🌈 SEE ALSO 🌈

Go read these when you’re done slaying:

dmenu(1), rofi(1), cclip(1), swaymsg(1), uwsm(1), systemd-run(1)

Project homepage: https://github.com/Mjoyufull/fsel

And that’s the page, bestie 💖 — version 3.6.0-kiwicrab, dated 2026-07-20. You ate, fr fr. 🎀✨

📦 where this page comes from