.TH FSEL 1 "2026-03-23" "3.3.1-kiwicrab" "User Commands"
.SH NAME
fsel \- fast TUI app launcher and fuzzy finder for GNU/Linux and *BSD
.SH SYNOPSIS
.B fsel
[\fIOPTIONS\fR]
.SH DESCRIPTION
.B fsel
is a terminal-based application launcher with advanced fuzzy search, dmenu compatibility, and clipboard history integration. It scans XDG desktop entries and optionally PATH executables, providing a fast interface for launching applications.
.PP
Features a sophisticated 12-tier search ranking system with configurable prioritization (\fIfrecency\fR, \fIrecency\fR, or \fIfrequency\fR). The ranking system prioritizes pinned apps, exact matches, prefix matches, and word-start matches, with configurable prefix depth for fine-tuning search behavior. Pin your favorites with Ctrl-Space for instant access.
.SH OPTIONS
.SS "App Launcher Options"
.BR \-c ", " \-\-config " " \fICONFIG\fR
Specify a config file (default: ~/.config/fsel/config.toml)
.TP
.BR \-r ", " \-\-replace
Replace existing fsel or cclip instances; terminates lingering processes before reopening the database
.TP
.B \-\-clear-history
Clear launch history database
.TP
.B \-\-clear-cache
Clear desktop file cache
.TP
.B \-\-refresh-cache
Force refresh of desktop file list (rescan for new apps)
.TP
.BR \-p ", " \-\-program " " \fINAME\fR
Launch program directly, bypassing TUI (requires at least 2 characters)
.TP
.BR \-ss " " \fISEARCH\fR
Pre-fill search in TUI (works with app launcher, dmenu, and cclip modes; must be last option)
.TP
.BR \-v ", " \-\-verbose
Increase verbosity level (can be used multiple times: -v, -vv, -vvv)
.TP
.B \-\-no-exec
Print selected application to stdout instead of launching
.TP
.BR \-\-launch-prefix " " \fICMD\fR
Launch applications through a custom command prefix (example: \fBrunapp --\fR)
.TP
.B \-\-systemd-run
Launch applications using systemd-run --user --scope (pairs with -d/--detach)
.TP
.B \-\-uwsm
Launch applications using uwsm app (pairs with -d/--detach)
.TP
.BR \-\-filter-desktop [=\fIno\fR]
Filter apps by OnlyShowIn/NotShowIn fields (default: yes)
.TP
.B \-\-list-executables-in-path
Include executables from $PATH alongside desktop apps
.TP
.B \-\-hide-before-typing
Hide list until first character is typed
.TP
.BR \-\-match-mode " " \fIMODE\fR
Match mode: 'fuzzy' or 'exact' (default: fuzzy)
.TP
.BR \-\-prefix-depth " " \fIN\fR
Character depth for prefix matching priority (default: 3). When query length is within this depth, prefix matches (exact, word-start) are prioritized over fuzzy matches.
.TP
.BR \-T ", " \-\-test
Enable debug/test mode with detailed logging. Logs are written to \fI~/.config/fsel/logs/\fR with timestamped filenames (fsel-debug-YYYYMMDD-HHMMSS-pidXXXXX.log). Logs include startup configuration, query changes, search snapshots with scoring breakdown, selection changes, launch events, and session statistics. Useful for debugging search ranking and analyzing performance.
.TP
.BR \-d ", " \-\-detach
Detach launched applications from terminal session (compatible with --launch-prefix, --systemd-run, and --uwsm)
.TP
.BR \-t ", " \-\-tty
Launch terminal apps in the current terminal (TTY mode). Replaces the fsel process with the launched app; use with -p/--program. Overrides terminal_launcher. Useful for TTY login sessions.
.SS "Dmenu Mode Options"
.TP
.B \-\-dmenu
Dmenu mode: read from stdin, output selection to stdout
.TP
.B \-\-dmenu0
Like --dmenu but null-separated input
.TP
.BR \-\-password [=\fICHAR\fR]
Password mode: mask input (default char: *)
.TP
.B \-\-index
Output index instead of text
.TP
.BR \-\-with-nth " " \fICOLS\fR
Display only specified columns (comma-separated, e.g., 1,3)
.TP
.BR \-\-accept-nth " " \fICOLS\fR
Output only specified columns
.TP
.BR \-\-match-nth " " \fICOLS\fR
Match against only specified columns
.TP
.BR \-\-delimiter " " \fICHAR\fR
Column delimiter (default: space)
.TP
.B \-\-only-match
Don't allow custom input, only return selected items
.TP
.B \-\-exit-if-empty
Exit immediately if stdin is empty
.TP
.BR \-\-select " " \fISTRING\fR
Pre-select first matching entry
.TP
.BR \-\-select-index " " \fIN\fR
Pre-select entry at index n
.TP
.B \-\-auto-select
Auto-select when only one match remains
.TP
.B \-\-prompt-only
Prompt-only mode: no list, just input
.SS "Clipboard Mode Options"
.TP
.B \-\-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); no external viewer required.
.TP
.BR \-\-tag " " \fINAME\fR
Filter clipboard items by tag (use with --cclip)
.TP
.B \-\-tag list
List all tags (use with --cclip)
.TP
.BR \-\-tag " list " \fINAME\fR
List items with specific tag (use with --cclip)
.TP
.B \-\-tag clear
Clear tag metadata from fsel database (colors, emojis). Does not remove tags from cclip entries.
.TP
.B \-\-tag wipe
Wipe ALL tags from cclip entries (requires cclip 3.2+). Removes the tag text from actual clipboard items.
.TP
.B \-\-cclip-show-tag-color-names
Show tag color names in clipboard item display (use with --cclip)
.SS "General Options"
.TP
.BR \-h
Show concise help overview
.TP
.BR \-H ", " \-\-help
Show detailed tree-style help covering all modes
.TP
.BR \-T ", " \-\-test
Enable debug/test mode with detailed logging. See App Launcher Options section for full description.
.TP
.BR \-V ", " \-\-version
Show version number
.TP
.BR \-t ", " \-\-tty
Launch in current terminal (TTY mode). See App Launcher Options.
.SH CONFIGURATION
Configuration file: \fI~/.config/fsel/config.toml\fR
.PP
Example configuration:
.PP
.nf
.RS
# 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
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" }]
.RE
.fi
.PP
See the example config.toml and keybinds.toml for all available options.
.SH KEYBOARD SHORTCUTS
.SS "Navigation"
.TP
.BR "↑/↓" " or " "Ctrl-P/Ctrl-N"
Navigate up/down
.TP
.BR "←/→"
Jump to top/bottom of list
.TP
.BR "Enter" " or " "Ctrl-Y"
Launch selected application
.TP
.BR "Ctrl-Space"
Toggle pin/favorite for selected app (pinned apps always appear first)
.TP
.BR "Esc" " or " "Ctrl-Q" " or " "Ctrl-C"
Exit
.TP
.B Backspace
Remove characters from search
.TP
.B Tab/Shift-Tab
Navigate down/up (alternative)
.TP
.B Home/End
Jump to first/last item
.SS "Clipboard Mode Keybinds"
.TP
.BR "Alt-i"
Open fullscreen image preview for selected clipboard item (native TUI; press Esc or q to return)
.TP
.BR "Ctrl-T"
Tag selected clipboard item
.TP
.BR "Alt-Delete"
Delete selected clipboard item (runs cclip delete). Selection and scroll position are preserved after deletion.
.SS "Mouse Support"
.TP
.B Hover
Select application
.TP
.B Click
Launch application
.TP
.B Scroll
Navigate list (selection follows mouse position)
.PP
All keybinds can be customized via \fI~/.config/fsel/keybinds.toml\fR or in the [keybinds] section of config.toml.
.SH LAUNCH METHODS
.TP
.B Default
Standard execution
.TP
.B Custom Prefix
Launch applications through a custom prefix with \fB--launch-prefix\fR or [app_launcher].launch_prefix.
.TP
.B systemd-run
Launch applications in isolated systemd user scopes with \fB--systemd-run\fR flag.
.TP
.B uwsm
Launch applications through Universal Wayland Session Manager with \fB--uwsm\fR flag.
.TP
.B Detach
Use \fB-d/--detach\fR to prevent apps from being killed when terminal closes. Works standalone or combined with --launch-prefix, --systemd-run, or --uwsm.
.SH EXAMPLES
.SS "Basic Usage"
.TP
Launch fsel interactively:
.nf
.RS
fsel
.RE
.fi
.SS "Direct Launch"
.TP
Launch Firefox directly without TUI:
.nf
.RS
fsel -p firefox
.RE
.fi
.TP
Launch first match for "terminal":
.nf
.RS
fsel -p term
.RE
.fi
.TP
Launch with detach (GUI apps):
.nf
.RS
fsel --detach -p discord
fsel --launch-prefix "runapp --" -p discord
fsel --systemd-run -p code
.RE
.fi
.SS "Pre-filled Search"
.TP
Open TUI with "firefox" already searched:
.nf
.RS
fsel -ss firefox
.RE
.fi
.TP
Multi-word search (must be last option):
.nf
.RS
fsel --uwsm -vv -r -ss text editor
.RE
.fi
.TP
Pre-fill search in dmenu mode:
.nf
.RS
echo -e "firefox\\nchrome\\nfirefox-dev" | fsel --dmenu -ss fire
.RE
.fi
.TP
Pre-fill search in cclip mode:
.nf
.RS
fsel --cclip -ss image
.RE
.fi
.SS "Dmenu Mode"
.TP
Basic dmenu replacement:
.nf
.RS
echo -e "Option 1\\nOption 2\\nOption 3" | fsel --dmenu
.RE
.fi
.TP
Process killer:
.nf
.RS
ps aux | fsel --dmenu --with-nth 2,11 --accept-nth 2 | xargs kill
.RE
.fi
.TP
Git branch switcher:
.nf
.RS
git branch | fsel --dmenu --select main | xargs git checkout
.RE
.fi
.TP
SSH connection picker:
.nf
.RS
grep "^Host " ~/.ssh/config | fsel --dmenu --with-nth 2 | xargs ssh
.RE
.fi
.TP
Window switcher (Sway):
.nf
.RS
swaymsg -t get_tree | jq -r '..|select(.name)|.name' | fsel --dmenu
.RE
.fi
.SS "Clipboard History"
.TP
Browse clipboard history (requires cclip):
.nf
.RS
fsel --cclip
.RE
.fi
.TP
Filter by tag:
.nf
.RS
fsel --cclip --tag prompt
fsel --cclip --tag code
.RE
.fi
.TP
List all tags:
.nf
.RS
fsel --cclip --tag list
.RE
.fi
.TP
List items with specific tag (verbose):
.nf
.RS
fsel --cclip --tag list prompt -vv
.RE
.fi
.TP
Clear fsel tag metadata:
.nf
.RS
fsel --cclip --tag clear
.RE
.fi
.TP
Wipe ALL tags from cclip entries:
.nf
.RS
fsel --cclip --tag wipe
.RE
.fi
.SH ENVIRONMENT
.TP
.B XDG_CONFIG_HOME
User config directory (default: ~/.config)
.TP
.B XDG_DATA_HOME
User data directory (default: ~/.local/share)
.TP
.B XDG_DATA_DIRS
System data directories (default: /usr/local/share:/usr/share)
.TP
.B XDG_CURRENT_DESKTOP
Used for desktop environment filtering (OnlyShowIn/NotShowIn)
.TP
.B WAYLAND_DISPLAY
Used to detect Wayland vs X11 for clipboard operations
.TP
.B FSEL_*
Environment variables with FSEL_ prefix override config file settings
.SH FILES
.TP
.I ~/.config/fsel/config.toml
User configuration file
.TP
.I ~/.config/fsel/keybinds.toml
Keybind customization file (optional, can use [keybinds] in config.toml)
.TP
.I ~/.local/share/fsel/hist_db.redb
Launch history, frecency data, and pinned apps database (redb format)
.TP
.I ~/.local/share/fsel/fsel-fsel.lock
Lock file for single instance (app launcher mode)
.TP
.I ~/.cache/fsel/fsel-cclip.lock
Lock file for single instance (cclip mode)
.TP
.I ~/.config/fsel/logs/fsel-debug-*.log
Debug log files (created when using -T/--test flag)
.TP
.I /usr/share/applications/*.desktop
System desktop entries
.TP
.I ~/.local/share/applications/*.desktop
User desktop entries
.SH EXIT STATUS
.TP
.B 0
Success
.TP
.B 1
Error occurred
.SH BUGS
Report bugs to: https://github.com/Mjoyufull/fsel/issues
.SH AUTHOR
Mjoyufull <https://github.com/Mjoyufull>
.PP
Original gyr by Namkhai B.
.SH SEE ALSO
.BR dmenu (1),
.BR rofi (1),
.BR cclip (1),
.BR swaymsg (1),
.BR uwsm (1),
.BR systemd-run (1)
.PP
Project homepage: https://github.com/Mjoyufull/fsel