Metadata-Version: 2.4
Name: tuil
Version: 0.1.0
Summary: fzf-driven terminal app launcher with install management, sudo caching, alias, and keybind setup
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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`](https://github.com/junegunn/fzf) on your `PATH`
- `sudo` (only touched if you install something through a system package manager)
## Install
 
From a clone of this repo:
 
```bash
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:
 
```bash
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
 
```markdown
![Main menu](screenshots/main-menu.png)
```
 

