{"id":48083431,"url":"https://github.com/Mjoyufull/fsel","last_synced_at":"2026-04-20T00:01:40.399Z","repository":{"id":313691626,"uuid":"1051967738","full_name":"Mjoyufull/fsel","owner":"Mjoyufull","description":"Fast TUI app launcher for GNU/Linux and *BSD","archived":false,"fork":false,"pushed_at":"2026-04-15T01:03:31.000Z","size":577,"stargazers_count":321,"open_issues_count":4,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-15T03:26:13.804Z","etag":null,"topics":["app-launcher","bsd","clipboard-manager","dmenu","hyprland","launcher","linux","ratatui","rust","tui","tui-app"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mjoyufull.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Mjoyufull"}},"created_at":"2025-09-07T05:33:35.000Z","updated_at":"2026-04-15T01:03:05.000Z","dependencies_parsed_at":"2025-09-07T22:12:41.266Z","dependency_job_id":"c798f72e-e3c9-410f-93f6-d760642819a2","html_url":"https://github.com/Mjoyufull/fsel","commit_stats":null,"previous_names":["mjoyufull/gyr","mjoyufull/fsel"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/Mjoyufull/fsel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mjoyufull%2Ffsel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mjoyufull%2Ffsel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mjoyufull%2Ffsel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mjoyufull%2Ffsel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mjoyufull","download_url":"https://codeload.github.com/Mjoyufull/fsel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mjoyufull%2Ffsel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32027234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app-launcher","bsd","clipboard-manager","dmenu","hyprland","launcher","linux","ratatui","rust","tui","tui-app"],"created_at":"2026-04-04T15:00:20.934Z","updated_at":"2026-04-20T00:01:40.388Z","avatar_url":"https://github.com/Mjoyufull.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n\n  ![Logo](./assets/fsel.png)\n\n*(fast select)*\n\n  [![License](https://img.shields.io/crates/l/fsel?style=flat-square)](https://github.com/Mjoyufull/fsel/blob/main/LICENSE)\n  ![written in Rust](https://img.shields.io/badge/language-rust-red.svg?style=flat-square)\n\n  Fast TUI app launcher and fuzzy finder for GNU/Linux and \\*BSD\n\n  \u003cimg width=\"860\" height=\"1019\" alt=\"Screenshot_20251006-032156\" src=\"https://github.com/user-attachments/assets/777bd0a4-eb52-4014-837b-d361ab57cfff\" /\u003e\n\n\n\n\u003c/div\u003e\n\n## Table of Contents\n\n- [Requirements](#requirements)\n- [Quickstart](#quickstart)\n- [Documentation](#documentation)\n- [Install](#install)\n- [Usage](#usage)\n- [Configuration](#configuration)\n  - [Environment variable overrides](#environment-variable-overrides)\n- [Contributing](#contributing)\n- [Troubleshooting](#troubleshooting)\n- [License](#license)\n\n**Start Here:** [Detailed Usage Guide](./USAGE.md)\n\n## Requirements\n\n**Build Requirements:**\n- Rust 1.94+ **stable** (NOT nightly)\n  - Install: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`\n  - Verify: `rustc --version` (should show stable, not nightly)\n  - If using nightly: `rustup default stable`\n- Cargo (comes with Rust)\n\n**Runtime Requirements:**\n- GNU/Linux or *BSD\n- Terminal emulator\n\n**Optional:**\n- [`cclip`](https://github.com/heather7283/cclip) - for clipboard history mode\n- Kitty, Sixel-, or Halfblocks-capable terminal - for native inline image previews in cclip mode (see [ratatui-image](https://github.com/benjajaja/ratatui-image))\n\n**Note:** Image previews in cclip mode use built-in [ratatui-image](https://github.com/benjajaja/ratatui-image) (no external viewer). Versions before 3.1.0 required `chafa` for image previews; 3.1.0 and later do not.\n\n## Quickstart\n\nGet up and running in 30 seconds:\n\n```sh\n# Install with Nix (recommended)\nnix run github:Mjoyufull/fsel\n\n# Or install from Cargo\ncargo install fsel@3.4.1-kiwicrab\n\n# Launch fsel\nfsel\n\n# Use as dmenu replacement\necho -e \"Option 1\\nOption 2\\nOption 3\" | fsel --dmenu\n\n# Browse clipboard history (requires cclip)\nfsel --cclip\n```\n\nThat's it. Type to search, arrow keys to navigate, Enter to launch.\n\nNeed install variants, launch methods, or mode-specific examples? See [USAGE.md](./USAGE.md).\n\n\n## Install\n\n#### Option 1: Nix Flake (Recommended)\n\n* Build and run with Nix flakes:\n    ```sh\n    $ nix run github:Mjoyufull/fsel\n    ```\n\n* Add to your profile:\n    ```sh\n    $ nix profile add github:Mjoyufull/fsel\n    ```\n\n* Add to your `flake.nix` inputs:\n    ```nix\n    {\n      inputs.fsel.url = \"github:Mjoyufull/fsel\";\n      # ... rest of your flake\n    }\n    ```\n\n#### Option 2: Cargo\n\n* Install from [crates.io](https://crates.io/crates/fsel):\n    ```sh\n    $ cargo install fsel@3.4.1-kiwicrab\n    ```\n* To update later:\n    ```sh\n    $ cargo install fsel@3.4.1-kiwicrab --force\n    ```\n* Or install latest version (check [releases](https://github.com/Mjoyufull/fsel/releases)):\n    ```sh\n    $ cargo search fsel  # See available versions\n    $ cargo install fsel@\u003cversion\u003e\n    ```\n\n#### Option 3: AUR (Arch Linux)\n\n* Install the git version with your favorite AUR helper:\n    ```sh\n    $ yay -S fsel-bin\n    # or\n    $ paru -S fsel-git\n    ```\n* Or manually:\n    ```sh\n    $ git clone https://aur.archlinux.org/fsel-bin.git\n    $ cd fsel-bi\n    $ makepkg -si\n    ```\n#### Option 4: Void linux (Unoffical Repo)\n\n* Install fsel on void\n    ```sh\n    echo repository=https://raw.githubusercontent.com/Event-Horizon-VL/blackhole-vl/repository-x86_64 | sudo tee /etc/xbps.d/20-repository-extra.conf\n    sudo xbps-install -S fsel\n    ```\n#### Option 5: Build from source\n\n* Install [Rust](https://www.rust-lang.org/learn/get-started) stable\n* Build:\n    ```sh\n    $ git clone https://github.com/Mjoyufull/fsel \u0026\u0026 cd fsel\n    $ cargo build --release\n    ```\n* Copy `target/release/fsel` to somewhere in your `$PATH`\n* (Optional) Create a dmenu symlink for drop-in compatibility:\n    ```sh\n    $ ./create_dmenu_symlink.sh\n    ```\n    Or manually: `ln -s $(which fsel) ~/.local/bin/dmenu`\n\n### Optional Dependencies\n\n* **uwsm** - Universal Wayland Session Manager (for `--uwsm` flag)\n* **systemd** - For `--systemd-run` flag\n* [**cclip**](https://github.com/heather7283/cclip) - Clipboard manager (for `--cclip` mode)\n* **Kitty, Foot, WezTerm, or other Sixel/Kitty/Halfblocks-capable terminal** - For native inline image previews in cclip mode (powered by [ratatui-image](https://github.com/benjajaja/ratatui-image); no chafa needed in 3.1.0+)\n* [**otter-launcher**](https://github.com/kuokuo123/otter-launcher) - Pairs nicely with fsel for a complete launcher setup see [Usage](./USAGE.md)\n\n## Usage\n\n### Interactive Mode\n\nRun `fsel` from a terminal to open the interactive TUI launcher.\n\n```sh\n# Launch fsel\nfsel\n\n# Pre-fill search (must be last)\nfsel -ss firefox\n\n# Direct launch (no UI)\nfsel -p firefox\n```\n\n**Highlights:**\n- **Advanced Search Ranking**: Configurable scoring with `frecency`, `recency`, or `frequency`\n- **Smart Matching**: Searches names, descriptions, keywords, and categories\n- **Pin/Favorite Apps**: Press Ctrl-Space to pin apps - pinned apps always appear first\n- **Match Modes**: Fuzzy (default) or exact matching\n\nSee [USAGE.md - App Launcher](./USAGE.md#app-launcher) for TTY mode, launch prefixes, `--detach`, cache management, `--replace`, and more.\n\n### Direct Launch Mode\n\nLaunch applications directly from the command line without opening the TUI:\n\n```sh\n# Launch Firefox directly\nfsel -p firefox\n\n# Launch the best fuzzy match for \"terminal\" (default match mode)\nfsel -p terminal\n\n# Partial names work while match_mode is fuzzy\nfsel -p fire  # Finds Firefox\n\n# Exact mode requires an exact app or executable name\nfsel --match-mode=exact -p firefox\nfsel --match-mode=exact -p fire   # Fails: no exact match\n\n# Combine with launch options\nfsel --launch-prefix=\"runapp --\" -p discord\nfsel --uwsm -p discord\nfsel --systemd-run -vv -p code\n```\n\n### Dmenu Mode\n\nFsel includes a full dmenu replacement mode that reads from stdin and outputs selections to stdout:\n\n```sh\n# Basic dmenu replacement\necho -e \"Option 1\\nOption 2\\nOption 3\" | fsel --dmenu\n\n# Display only specific columns (like cut)\nps aux | fsel --dmenu --with-nth 2,11  # Show only PID and command\n\n# Use custom delimiter\necho \"foo:bar:baz\" | fsel --dmenu --delimiter \":\"\n\n# Pipe from any command\nls -la | fsel --dmenu\nfind . -name \"*.rs\" | fsel --dmenu\ngit log --oneline | fsel --dmenu\n```\n\nSee [USAGE.md - Dmenu Mode](./USAGE.md#dmenu-mode) for column operations, password input, pre-selection, exact matching, `--dmenu0`, and prompt-only mode.\n\n### Clipboard History Mode\nRequires [cclip](https://github.com/heather7283/cclip).\n\u003cimg width=\"853\" height=\"605\" alt=\"image\" src=\"https://github.com/user-attachments/assets/0bf71952-f09a-4ce2-8807-bca1003c8daf\" /\u003e\n\nBrowse and select from your clipboard history with image previews:\n\n```sh\n# Browse clipboard history with cclip integration\nfsel --cclip\n\n# Filter by tag\nfsel --cclip --tag prompt\n\n# List all tags\nfsel --cclip --tag list\n\n# List items with specific tag (verbose shows details)\nfsel --cclip --tag list prompt -vv\n\n# Clear tag metadata from fsel database\nfsel --cclip --tag clear\n\n# Show tag color names in display\nfsel --cclip --cclip-show-tag-color-names\n```\n\nSee [USAGE.md - Clipboard Mode](./USAGE.md#clipboard-mode) for tag management, keybindings, inline image details, and more clipboard-specific behavior.\n\n### Command Line Help\n\n```sh\n# Quick overview grouped by mode/flags\nfsel -h\n\n# Full tree-style reference covering every option\nfsel -H\n\n# Show verbose output\nfsel -vvv\n```\n\nSee [USAGE.md](./USAGE.md) for more examples, launch methods, scripting recipes, debugging notes, [environment variables](./USAGE.md#environment-variables), and advanced usage.\n\n## Configuration\n\nConfig file: `~/.config/fsel/config.toml`\n\n### Basic Setup\n\n```toml\n# Colors\nhighlight_color = \"LightBlue\"\ncursor = \"█\"\n\n# App launcher\nterminal_launcher = \"alacritty -e\"\n\n# Pin/favorite settings (root-level UI options)\npin_color = \"rgb(255,165,0)\"       # Color for pin icon (orange)\npin_icon = \"📌\"                     # Icon for pinned apps\n\n[app_launcher]\nfilter_desktop = true              # Filter apps by desktop environment\nfilter_actions = false            # Keep desktop actions visible; set true to hide them\nlist_executables_in_path = false   # Show CLI tools from $PATH\nmatch_mode = \"fuzzy\"               # \"fuzzy\" or \"exact\"\nranking_mode = \"frecency\"          # \"frecency\", \"recency\", or \"frequency\"\npinned_order = \"ranking\"           # \"ranking\", \"alphabetical\", \"oldest_pinned\", \"newest_pinned\"\n```\n\nField placement matters. Root-level UI options and `[app_launcher]` / `[dmenu]` / `[cclip]` sections are validated separately.\nSee [config.toml](./config.toml) and [keybinds.toml](./keybinds.toml) for all options with detailed comments.\n`[app_launcher].match_mode = \"exact\"` also applies to `-p/--program`, where it requires an exact app or executable name.\n\n### Environment variable overrides\n\nAfter 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`.\n\n- **Root / shared keys:** `FSEL_` plus the uppercase TOML key (e.g. `match_mode` → `FSEL_MATCH_MODE`).\n- **Section keys:** `FSEL_DMENU_*`, `FSEL_CCLIP_*`, and `FSEL_APP_LAUNCHER_*` mirror `[dmenu]`, `[cclip]`, and `[app_launcher]` fields.\n\n```sh\nFSEL_MATCH_MODE=exact fsel\nFSEL_APP_LAUNCHER_FILTER_ACTIONS=true fsel\nFSEL_HIGHLIGHT_COLOR=Cyan FSEL_DMENU_DELIMITER=: fsel --dmenu \u003c items.txt\n```\n\n`man fsel` summarizes this under **ENVIRONMENT**. For the full variable list, see [Environment variables](./USAGE.md#environment-variables) in [USAGE.md](./USAGE.md).\n\n### Window Manager Integration\n\n**Sway/i3:**\n```sh\n# ~/.config/sway/config\nset $menu alacritty --title launcher -e fsel\nbindsym $mod+d exec $menu\nfor_window [title=\"^launcher$\"] floating enable, resize set width 500 height 430, border none\n\n# Clipboard history\nbindsym $mod+v exec 'alacritty --title clipboard -e fsel --cclip'\n```\n\n**Hyprland:**\n```sh\n# ~/.config/hypr/hyprland.conf\nbind = $mod, D, exec, alacritty --title launcher -e fsel\nwindowrule {\n    match:title = launcher\n    float = on \n    center = on \n    size = 500 430\n}\n```\n\n**Niri:**\n```sh\n# ~/.config/niri/config.kdl\nwindow-rule {\n    match title=\"launcher\"\n    open-floating true\n}\n\n# Add inside binds { ... }\nMod+D { spawn \"alacritty\" \"--title\" \"launcher\" \"-e\" \"fsel\"; }\n```\n\n**dwm/bspwm/any WM:**\n```sh\n# Use dmenu mode\nbindsym $mod+d exec \"fsel --dmenu | xargs swaymsg exec --\"\n```\n\n## Contributing\n\nContributions are welcome! Whether you're reporting bugs, suggesting features, or submitting code, we appreciate your help making fsel better.\n\n### How to Contribute\n\n1. **Bug Reports \u0026 Feature Requests**: Open an issue on [GitHub Issues](https://github.com/Mjoyufull/fsel/issues)\n2. **Pull Requests**: Fork the repo, create a feature branch, and submit a PR\n3. **Code Style**: Run `cargo fmt` and `cargo clippy` before submitting\n4. **Testing**: Ensure `cargo test` and `cargo build --release` pass\n\n### Development Workflow\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines on:\n- Branch naming conventions\n- Commit message format\n- Pull request process\n- Code review standards\n- Release procedures\n\nAll contributors are valued and appreciated. Your name will be added to the contributors list, and significant contributions will be highlighted in release notes.\n\nThank you for helping improve fsel!\n\n## Philosophy\n\nfsel 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.\n\n**This means:**\n- It's built for my workflow first, but PRs for bug fixes and useful features are welcome as long as they fit in scope.\n- Older versions and the original gyr exist if you want something more minimal.\n---\n\n## Troubleshooting\n\n**Apps not showing up?**\n- Check `$XDG_DATA_DIRS` includes `/usr/share/applications`\n- Try `--filter-desktop=no` to disable desktop filtering\n- Use `-vvv` for debug info\n\n**Mouse not working?**\n- Check your terminal supports mouse input\n- Try `disable_mouse = false` in config\n\n**Images not showing in cclip mode?**\n- Use a Kitty-, Sixel-, or Halfblocks-capable terminal (e.g. Kitty, Foot, WezTerm). Image preview uses built-in [ratatui-image](https://github.com/benjajaja/ratatui-image); no chafa or other external viewer is needed (3.1.0+).\n- Check `image_preview = true` in config\n- Images render inside the content panel; press Alt+i for fullscreen preview\n\n**Fuzzy matching too loose?**\n- Try `--match-mode=exact` for stricter matching\n- Or set `match_mode = \"exact\"` in config\n\n**Too many desktop action entries?**\n- Use `--filter-actions` to hide desktop actions like \"New Window\"\n- Or set `filter_actions = true` under `[app_launcher]`\n\n**Terminal apps not launching?**\n- Set `terminal_launcher` in config\n- Example: `terminal_launcher = \"kitty -e\"`\n\n## Credits\n\nFork of [gyr](https://git.sr.ht/~nkeor/gyr) by Namkhai B.\n\n## License\n\n[BSD 2-Clause](./LICENSE) (c) 2020-2022 Namkhai B., Mjoyufull\n","funding_links":["https://github.com/sponsors/Mjoyufull"],"categories":["💻 Apps"],"sub_categories":["🚀 Productivity and Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMjoyufull%2Ffsel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMjoyufull%2Ffsel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMjoyufull%2Ffsel/lists"}