veet

README

Universal Linux Application Uninstaller & Deep-Clean Residual Purger
An interactive terminal system utility that detects installed software across package managers and automates complete removal of binaries, user caches, configuration files, and residual logs in one confirmed action.

---

Technical Overview

When software is uninstalled using conventional Linux package managers (pacman -R, apt remove, dnf remove, flatpak uninstall), only package-managed system files (/usr/bin, /usr/share) are modified. User-space directories remain unmanaged:

• ~/.config/<app> (user configuration state)
• ~/.cache/<app> (accumulated runtime caches, shader caches, webview stores)
• ~/.local/share/<app> (local application data and databases)
• ~/.local/state/<app> (session and state histories)
• /var/log/<app> and systemd journal archives

Over extended usage, unmanaged leftovers consume significant disk storage. Modern Linux distributions also feature package manager fragmentation across native repositories, universal formats, and language toolchains.

VEET bridges this gap by scanning all installed targets concurrently, staging candidate residual paths for user verification, and executing atomic uninstalls with batched privilege elevation.

---

Comparison Matrix

Feature	pacman -R / apt remove	flatpak uninstall	bleachbit	veet
Binary Removal	Yes	Yes	No	Yes
User Configuration Cleanup (~/.config)	No	No	Partial	Yes (Inspected & Staged)
User Cache Cleanup (~/.cache)	No	No	Yes	Yes (Inspected & Staged)
Universal Multi-Source Aggregator	No	No	No	Yes (15+ package managers)
Orphaned Dependencies Detection	Manual query	No	No	Yes (Live detection)
AppImage & Portable Binary Scanner	No	No	No	Yes (Auto-discovered)
Interactive Terminal UI (TUI)	No	No	GTK Only	Yes (Zero-latency Bubble Tea)
Pre-execution Dry-run Inspection	Partial	Partial	Yes	Yes (Full path inspection)
Batched Sudo Elevation	Per command	N/A	Full root required	Yes (Single prompt per batch)

---

Core Capabilities

Multi-Source Parallel Detection Concurrently queries system package managers (pacman/AUR, apt, dnf, zypper), sandboxed formats (Flatpak, Snap), portable bundles (AppImage), and language toolchains (npm -g, pipx, cargo, gem, go install) with zero-cost skipping for absent tools.	Deep Residual Cleanup Automates residual discovery across user configurations, cached runtime stores, desktop integration entries, icons, and system paths, staging each candidate before disk execution.
Orphaned Dependency Pruning Live detection of unneeded dependency packages across native package managers (pacman -Qdt, apt autoremove, dnf repoquery --unneeded) ready for safe reclamation.	System Log & Journal Vacuum Identifies bloated systemd journal storage (/var/log/journal) and rotated compressed log archives (/var/log/*.gz) with integrated elevated vacuum routines.
Interactive Navigation & Telemetry Instant category switching (1–6), four-mode list sorting (o) for rapid disk bloat identification, and in-place staged path inspection (p).	Sudo Batching & Anti-Brick Safety Core system components (glibc, linux, systemd, active shell) are protected from selection. System paths are batched into a single elevated transaction.

---

Installation

Option 1: Automated Script Installation (Recommended)

Downloads, compiles with binary optimizations (-ldflags="-s -w"), installs to ~/.local/bin/veet, and configures shell autocompletions:

curl -sSL https://raw.githubusercontent.com/swadhinbiswas/veet/main/install.sh | bash

Or from local clone:

./install.sh

---

Option 2: Go Package Manager

Install directly via the standard Go toolchain (requires Go 1.24+):

go install github.com/swadhinbiswas/veet@latest

Or install from local source:

go install .

---

Option 3: Manual Compilation via Makefile

git clone https://github.com/swadhinbiswas/veet.git
cd veet
make build
make install

[!NOTE] Ensure ~/.local/bin is present in your environment $PATH. If not, add export PATH="$PATH:$HOME/.local/bin" to your ~/.bashrc or ~/.zshrc.

---

Usage

Interactive Terminal Dashboard

Launch the zero-latency terminal user interface:

veet

---

Command Line Interface

VEET exposes non-interactive headless commands for automation, scripting, and CI auditing:

# Output installed application inventory table to stdout
veet scan

# Export machine-readable JSON inventory
veet scan --json

# Non-interactive deep-clean removal with preview
veet clean <package-name>

# Non-interactive removal scoped to specific source with confirmation
veet clean <package-name> --source flatpak --yes

---

Keybinding Reference

Keybinding	Action
1 – 6	Jump to stat card category (All, Flatpak, Snap, Tools, Cache, Reclaim)
[ / ] or ← / →	Cycle horizontally through top stat categories
↑ ↓ / j k	Navigate table selection cursor
Space	Toggle multi-select checkbox on active row
a	Select / deselect all visible filtered rows (skips protected components)
o / O	Cycle sort order (Size ↓, Name A-Z, Source, Date ↓)
p / P	Toggle staged filesystem paths inspector in details panel
/	Focus fuzzy search-as-you-type filter input
Tab / Shift+Tab	Cycle specific source filter dropdown (pacman, aur, flatpak, etc.)
Enter	Stage selected applications and open confirmation preview modal
c	1-key quick purge for user cache & residual files
e	Export audit inventory report to ~/.local/share/veet/apps-report.json
r	Trigger background rescan across all detectors
l	Open history audit log viewport
s	Open settings and protected components registry
h / ?	Toggle keybinding reference overlay
Esc	Dismiss active modal / blur search input
q / Ctrl+C	Quit VEET

---

Configuration

Custom Configuration (~/.config/veet/config.yaml)

VEET supports optional user configuration via YAML. Create ~/.config/veet/config.yaml to declare custom protected packages:

# Packages that VEET will refuse to stage or select for deletion
protected_packages:
  - custom-kernel-module
  - my-critical-service
  - proprietary-driver

System Architecture & Module Map

veet/
├── main.go               # Cobra CLI entrypoint (scan, clean, tui)
├── internal/
│   ├── model/            # Data types: AppInfo, RemovableFiles, Config, SourceMeta
│   ├── detector/         # Parallel detector engine (15+ source handlers)
│   ├── uninstaller/      # Staging engine, sudo batching & filesystem removal (Afero)
│   ├── history/          # Append-only audit logger (~/.local/share/veet/history.log)
│   └── ui/               # Bubble Tea & Lip Gloss TUI components
├── assets/               # Brand assets & custom vector icons
├── Makefile              # Build automation targets
├── install.sh            # Automated Bash installer
└── uninstall.sh          # Uninstaller script

---

Uninstallation

From Cloned Source Repository

./uninstall.sh

Manual Removal (Binary & Shell Completions)

If installed via go install or direct binary download:

# Remove executable binary
rm -f ~/.local/bin/veet

# Remove shell autocompletions
rm -f ~/.local/share/bash-completion/completions/veet
rm -f ~/.local/share/zsh/site-functions/_veet
rm -f ~/.config/fish/completions/veet.fish

# Optionally remove audit logs and configurations
rm -rf ~/.local/share/veet ~/.config/veet

---

Contributing

Contributions are welcome. Please refer to CONTRIBUTING.md for local development setup, detector implementation guides, and testing protocols.

---

License

VEET is open-source software licensed under the MIT License.