tuil 0.1.0

fzf-driven terminal app launcher with install management, sudo caching, alias, and keybind setup

termui

A fzf-driven launcher for your terminal (TUI) apps. Browse your tools, launch them, install what's missing, add your own, and trigger the whole thing with a hotkey.

The command you type/bind is termui; the installable package is called tuil (the name termui was already taken on PyPI).

Linux only. It relies on sudo, Linux package managers (pacman/apt-get/dnf/zypper/apk), ~/.bashrc / ~/.config/fish/config.fish for the alias, and Hyprland/Sway/i3/sxhkd/GNOME for the keybind. It won't run as-is on macOS or Windows.

Requirements

• Python 3.10+
• fzf on your PATH
• sudo (only touched if you install something through a system package manager)

Install

From a clone of this repo:

pipx install .

(or pip install --break-system-packages -e . for an editable dev install). Either way this gives you a real termui command on your PATH.

Once published, this will also work directly:

pipx install tuil

First run

The first time you run termui, a one-time wizard walks through:

1. Package manager detection — detects pacman, apt-get, dnf, zypper, or apk, and reports how many of the ~30 default tools are already installed.
2. Preload defaults? — yes seeds the list with common TUI tools, install commands auto-mapped to your detected package manager. No starts you with an empty, custom-only list.
3. Alias setup — pick a command name (default termui), added to ~/.bashrc and ~/.config/fish/config.fish, whichever exist.
4. Keybind setup — pick a modifier (SUPER/CTRL/ALT/SHIFT) and a key. It detects your window manager / desktop and wires up the binding accordingly:

   Environment	Where the bind goes	Apply it with
   Hyprland	~/.config/hypr/hyprland.conf	hyprctl reload
   Sway	~/.config/sway/config	swaymsg reload
   i3	~/.config/i3/config	i3-msg reload
   sxhkd (bspwm etc.)	~/.config/sxhkd/sxhkdrc	pkill -USR1 sxhkd
   GNOME	custom keybinding via gsettings	works immediately
   If none of these are detected, it skips the hotkey and tells you to bind the alias manually in your desktop's shortcut settings. The bind opens whatever terminal it finds on your system (kitty, alacritty, wezterm, foot, gnome-terminal, konsole, or xterm, in that order, or $TERMINAL if set) running termui.

This all only runs once, tracked in ~/.config/tuilauncher/state.json. Delete that file to redo the wizard.

Every session

Each launch asks fresh whether to cache sudo for that session (credentials don't persist between runs):

• Yes — one password prompt, then a background keep-alive so installs don't ask again.
• No — installs run normally; sudo prompts inline whenever a command needs it.

Using the menu

Option	What it does
(any app name)	Launch it if installed, otherwise prompt you to install it
[34] Install Package	Pick one missing tool and install it
[35] Install All	Install every missing tool in the list
[36] Add Custom Tool	Add your own entry — name, run command, install command, category, description
[00] Quit	Exit

Config file

Your app list lives at ~/.config/tuilauncher/apps.csv, pipe-delimited:

name|run_command|install_command|description|category

Edit it by hand if you'd rather skip the [36] Add Custom Tool menu.

Project layout

tuil/
├── pyproject.toml
├── README.md
├── .gitignore
└── src/
    └── tuil/
        ├── __init__.py
        └── cli.py

Screenshots

![Main menu](screenshots/main-menu.png)