{"id":16380864,"url":"https://github.com/biont/sway-launcher-desktop","last_synced_at":"2025-05-15T07:03:48.182Z","repository":{"id":35710496,"uuid":"216891506","full_name":"Biont/sway-launcher-desktop","owner":"Biont","description":"TUI Application launcher with Desktop Entry support. Made for SwayWM, but runs anywhere","archived":false,"fork":false,"pushed_at":"2024-11-12T20:38:58.000Z","size":185,"stargazers_count":641,"open_issues_count":23,"forks_count":31,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-15T07:03:02.616Z","etag":null,"topics":["application-autostart","bash","desktop-entries","desktop-files","dmenu-replacement","fzf","i3wm","launcher","menu","sway","swaywm","tui","xdg-basedir"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Biont.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2019-10-22T19:16:32.000Z","updated_at":"2025-05-14T15:27:44.000Z","dependencies_parsed_at":"2024-06-10T22:33:48.908Z","dependency_job_id":"c35b2634-3845-4b4e-b7c6-eaae0f9454db","html_url":"https://github.com/Biont/sway-launcher-desktop","commit_stats":{"total_commits":130,"total_committers":21,"mean_commits":6.190476190476191,"dds":"0.46923076923076923","last_synced_commit":"452b3ec083079b9da361cd75d2835b30e66ae84c"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fsway-launcher-desktop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fsway-launcher-desktop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fsway-launcher-desktop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fsway-launcher-desktop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Biont","download_url":"https://codeload.github.com/Biont/sway-launcher-desktop/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254291961,"owners_count":22046424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["application-autostart","bash","desktop-entries","desktop-files","dmenu-replacement","fzf","i3wm","launcher","menu","sway","swaywm","tui","xdg-basedir"],"created_at":"2024-10-11T03:52:40.750Z","updated_at":"2025-05-15T07:03:48.161Z","avatar_url":"https://github.com/Biont.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sway-launcher-desktop ![Build Status](https://github.com/Biont/sway-launcher-desktop/workflows/CI/badge.svg)\n\n![screenshot_2019-10-25-213740](https://user-images.githubusercontent.com/4208996/67599848-3a1f3680-f771-11e9-9715-da6e943ae14e.png)\n\nThis is a TUI-based launcher menu made with bash and the amazing [fzf](https://github.com/junegunn/fzf).\nDespite its name, it does not (read: no longer) depend on the Sway window manager in any way and can be used with just about any WM.\n\n## Features\n- Lists and executes available binaries\n- Lists and executes .desktop files (entries as well as actions)\n- Does not depend on `xdg-utils`. Just pure bash and `awk` (specifically gawk)\n- Shows a preview window containing `whatis` info of binaries and the `Comment=` section of .desktop files\n- History support which will highlight recently used entries\n- Colored output and glyphs for the different entry types\n- Entries are lazily piped into `fzf` eliminating any lag during startup\n- Optional support for the XDG Autostart specification\n- Executes arbitrary custom commands (if there are no other matches)\n\n## Installation\n\nMake sure you have `fzf` and `awk` installed and download this repository. \nTo be precise, the script specifically depends on GNU awk (`gawk`) so check what flavour your distribution provides.\n\nArch Linux users can also grab it from the AUR (thanks @turtlewit)\n\n* [sway-launcher-desktop](https://aur.archlinux.org/packages/sway-launcher-desktop/)\n* [sway-launcher-desktop-git](https://aur.archlinux.org/packages/sway-launcher-desktop-git/)\n\nConfigure it in Sway like this:\n```\nfor_window [app_id=\"^launcher$\"] floating enable, sticky enable, resize set 30 ppt 60 ppt, border pixel 10\nset $menu exec $term -a launcher -e /path/to/repo/sway-launcher-desktop.sh\nbindsym $mod+d exec $menu\n```\n(this example was made with `term=foot` in mind; it may need to be adjusted for other terminals)\n\nYou can override the default icons/glyphs by setting the appropriate GLYPH_ variable in your $menu command, e.g.:\n```\nset $menu exec $term -e env GLYPH_COMMAND=\"\" GLYPH_DESKTOP=\"\" GLYPH_PROMPT=\"? \" sway-launcher\n```\n\nIf `fzf` is not in your `$PATH` you can specify the path by supplying a value to the `FZF_COMMAND` variable.\n```\nset $menu exec $term -e env FZF_COMMAND=\"/path/to/fzf\" sway-launcher\n```\n\nBy default, the launcher will use a generic \u0026 WM-agnostic command to launch the selected program. \nHowever, it will detect if its output is being piped to another program and merely print \nthe selected command in that case - instead of launching it by itself. You can use this to integrate the launcher with other tools.\nFor example, if you wish to launch your programs with `swaymsg exec`, you can do that like this¹:\n\n```shell\n swaymsg exec \"$(./sway-launcher-desktop.sh)\"\n```\n\n### Set up a Terminal command\nSome of your desktop entries will probably be TUI programs that expect to be launched in a new terminal window. Those entries have the `Terminal=true` flag set and you need to tell the launcher which terminal emulator to use. Pass the `TERMINAL_COMMAND` environment variable with your terminal startup command to the script to use your preferred terminal emulator. The script will default to `$TERMINAL -e`\n\n### Configure application autostart\nIf you want to be able to autostart applications , this script provides a function to handle them for you. Simply run `sway-launcher-desktop.sh autostart` in your `.bashrc`, at the end of your i3/sway config, or wherever else you deem fit.\n\n### Configure fzf preview window\nYou can configure the fzf preview window using the environment variable `PREVIEW_WINDOW` (default: `up:2:noborder`). For example, if you prefer a taller window, you could use `PREVIEW_WINDOW=5:up`. The content of `PREVIEW_WINDOW` is passed to the `--preview-window` option, so check out the fzf manual for further details.\n\n## Extending the launcher\n\nIn addition to desktop application entries and binaries, you can extend `sway-launcher-desktop` with custom item providers.\nIt will read the configuration of custom item providers from `$HOME/.config/sway-launcher-desktop/providers.conf`.\nThe structure looks like this:\n\n```\n[my-provider]\nlist_cmd=echo -e 'my-custom-entry\\034my-provider\\034  My custom provider'\npreview_cmd=echo -e 'This is the preview of {1}'\nlaunch_cmd=notify-send 'I am now launching {1}'\npurge_cmd=command -v '{1}' || exit 43\n```\n\nThe `list_cmd` generated the list of entries. For each entry, it has to print the following columns, separated by the `\\034` field separator character:\n1. The item to launch. This will get passed to `preview_cmd` and `launch_cmd` as `{1}`\n2. The name of your provider (the same as what what you put inside the brackets, so `my-provider` in this example)\n3. The text that appears in the `fzf` window. You might want to prepend it with a glyph and add some color via ANSI escape codes\n4. (optional) Metadata that you can pass to `preview_cmd` and `launch_cmd` as `{2}`. For example, this is used to specify a specific Desktop Action inside a .desktop file\n\nThe `preview_cmd` renders the contents of the `fzf` preview panel. You can use the template variable `{1}` in your command, which will be substituted with the value of the selected item.\n\nThe `launch_cmd` is fired when the user has selected one of the provider's entries.\n\nThe `purge_cmd` is used as part of the `purge` function. It tests any entry of a provider. If the test exits with `43`, then the entry will be removed from the history file\n\nNote: Pass the environment variable `PROVIDERS_FILE` to read custom providers from another file than the default `providers.conf`.\nThe path in `PROVIDERS_FILE` can either be absolute or relative to `${HOME}/.config/sway-launcher-desktop/`.\n\n\n### Keeping builtin providers\nWhen a custom provider config is used, the default behaviour is to replace the hardcoded builtins. This is not always desirable if you merely wish to *add* something new. Luckily, the built-in providers only call specific functions of the main script, which are also accessible externally.\nSo you can simply mimick their behaviour by placing this in your config file:\n\n```\n[desktop]\nlist_cmd=/path/to/sway-launcher-desktop.sh list-entries\npreview_cmd=/path/to/sway-launcher-desktop.sh describe-desktop \"{1}\"\nlaunch_cmd=/path/to/sway-launcher-desktop.sh run-desktop '{1}' {2}\npurge_cmd=test -f '{1}' || exit 43\n\n[command]\nlist_cmd=/path/to/sway-launcher-desktop.sh list-commands\npreview_cmd=/path/to/sway-launcher-desktop.sh describe-command \"{1}\"\nlaunch_cmd=$TERMINAL_COMMAND {1}\npurge_cmd=command -v '{1}' || exit 43\n```\n\n## Launcher history file\n\nBy default, `sway-launcher-desktop` stores a history of commands to make frequently used entries available more quickly.\nThis history is stored in a file in `~/.cache/` (or `$XDG_CACHE_HOME`, if that environment variable is set).\nYou may change the file path and name by setting the environment variable `HIST_FILE` to the desired path.\nSetting the variable to an empty value disables the history feature entirely.\n\n### Housekeeping\nAfter a while, this history might grow and contain some invalid entries due to removed/renamed programs etc.\nYou can use `./sway-launcher-desktop.sh purge` to identify broken entries and remove them.\nConsider adding this command to a cronjob, startup script, or maybe even hook it into your package manager.\n\n\n## Troubleshooting\n\nDebug information is directed to file descriptor `3` and can be dumped using `./sway-launcher-desktop.sh 3\u003e\u003e ~/sway-launcher-desktop.log`\n\n---\n\n¹ If you want to use this as a keybinding though, this kind of shell substitution will not work inside the config file. [Here's a way to make it work](https://github.com/Biont/sway-launcher-desktop/issues/33#issuecomment-765145677)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiont%2Fsway-launcher-desktop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiont%2Fsway-launcher-desktop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiont%2Fsway-launcher-desktop/lists"}