veet

README

VEET

Universal Linux Application Uninstaller & Deep-Clean Residual Purger

A modern, high-performance TUI and CLI uninstallation suite for Linux.
Scan 17+ package managers concurrently, detect hidden configurations & cache bloat, inspect staged disk paths in real-time, and execute atomic uninstalls with single-pass privilege elevation.

Overview • Comparison • Capabilities • Installation • Usage • Search Syntax • Themes • Keybindings • Config

---

⚡ Technical Overview

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

• ~/.config/<app> (user configuration state & credentials)
• ~/.cache/<app> (accumulated runtime caches, shader caches, webview stores)
• ~/.local/share/<app> (local databases, media, and state)
• ~/.local/state/<app> (session histories and temporary state)
• ~/.var/app/<app> (Flatpak sandboxed data)
• ~/snap/<app> (Snap snapshots and application state)
• /var/log/<app> and systemd journal archives

Over time, unmanaged leftovers consume gigabytes of valuable storage. Modern Linux setups also suffer from package fragmentation across native repositories, universal containers, and developer toolchains.

VEET bridges this gap: it scans all installed targets across 17+ package managers concurrently, stages candidate residual paths for interactive inspection, and executes atomic uninstalls with batched, single-prompt privilege elevation.

---

📊 Comparison Matrix

Feature	pacman -R / apt	flatpak uninstall	bleachbit	veet
Binary Removal	Yes	Yes	No	Yes (17+ Sources)
User Config Cleanup (~/.config)	No	No	Partial	Yes (Inspected & Staged)
User Cache Cleanup (~/.cache)	No	No	Yes	Yes (Inspected & Staged)
Sandbox Cleanup (~/.var/app, ~/snap)	No	Partial	No	Yes (Deep detection)
Universal Multi-Source Aggregator	No	No	No	Yes (Native, Containers, CLI tools)
Orphaned Dependency Pruning	Manual query	No	No	Yes (Live detection)
Portable Binary Scanner (AppImage)	No	No	No	Yes (Auto-discovered)
Interactive Terminal UI (TUI)	No	No	GTK Only	Yes (7 Themes, Streaming Scan Matrix)
Advanced Query Syntax (@source, >size)	No	No	No	Yes (Full modifier support)
Pre-execution Dry-run Inspection	Partial	Partial	Yes	Yes (Full path inspection & --dry-run)
Batched Sudo Elevation	Per command	N/A	Full root required	Yes (Single prompt per batch)

---

🌟 Core Capabilities

17+ Package Detectors Concurrently queries system package managers (pacman/AUR, apt, dnf, zypper), sandboxed containers (Flatpak, Snap), portable bundles (AppImage, Homebrew, Nix), and language toolchains (npm -g, pipx, cargo, gem, go install) with zero-cost skipping for uninstalled tools.	Deep Residual Cleanup Automates residual discovery across user configurations, cached runtime stores (~/.var/app, ~/snap, ~/.local), desktop integration entries, icons, and system paths, staging each candidate before execution.
Streaming Scan Matrix Live, responsive startup matrix displaying real-time progress across all 17 detectors with color-coded status tiles, animated progress bar, package counters, live elapsed timer, and background discovery feed.	Orphan & Dependency Pruning Live detection and safe reclamation of unneeded dependency packages across native package managers (pacman -Qdt, apt autoremove, dnf repoquery --unneeded).
System Log & Journal Vacuum Identifies bloated systemd journal storage and cleans it safely via journalctl --vacuum alongside rotated compressed log archives with integrated elevated vacuum routines.	Anti-Brick Safety & Sudo Batching Core system components (glibc, linux, systemd, active shell) are protected from selection. System paths are batched into a single elevated transaction.

---

📥 Installation

Option 1: Arch Linux (AUR)

Install via your preferred AUR helper:

yay -S veet
# or
paru -S veet

For the latest development git build:

yay -S veet-git

---

Option 2: Automated Script Installation (Recommended)

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

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

# Or install a specific pinned release tag (e.g. v1.1.0)
curl -sSL https://raw.githubusercontent.com/swadhinbiswas/veet/v1.1.0/install.sh | VEET_VERSION=v1.1.0 bash

Or from a local clone:

./install.sh

---

Option 3: Go Package Manager

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

go install github.com/swadhinbiswas/veet@latest

---

Option 4: 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 (TUI)

Launch the full-featured interactive terminal user interface:

veet

---

Headless Command Line Interface (CLI)

VEET exposes non-interactive headless subcommands for automation, scripting, and system auditing:

# Output installed application inventory table to stdout
veet scan

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

# Deep-clean uninstall one or multiple applications (interactive confirmation)
veet clean app1 app2

# Inspect staged paths without deleting anything
veet clean <package-name> --dry-run

# Non-interactive deep-clean removal with auto-confirmation
veet clean <package-name> --yes

# Detect and prune orphaned packages
veet orphans --clean --yes

# Inspect and purge leftover caches and directories
veet cache --clean --yes

# View or clear uninstallation audit history
veet history
veet history --clear

---

🔍 Search Syntax

Press / in the TUI to focus the search bar. VEET supports powerful query modifiers:

Syntax	Example	Description
@<source>	@flatpak, @aur, @snap, @brew, @nix	Filter by specific package manager
><size>	>100M, >1G, >500K	Filter applications larger than specified size
<<size>	<50M, <10M	Filter applications smaller than specified size
protected:<bool>	protected:true, protected:false	Filter by protected component status
<name>	gimp, code, node	Fuzzy-match application name

[!TIP] Combine Modifiers: @flatpak >200M gimp filters for Flatpak apps larger than 200MB matching "gimp".

---

🎨 Theming

VEET features 7 hand-crafted color palettes to seamlessly integrate with your terminal setup. Configure your theme in ~/.config/veet/config.yaml:

theme: catppuccin  # Options: cyan, catppuccin, nord, dracula, gruvbox, tokyo-night, monokai

Theme	Preview Description
cyan (Default)	High-contrast neon cyan & indigo accents
catppuccin	Warm pastel Catppuccin Mocha palette with mauve highlights
nord	Clean arctic Nord blues with frost cyan accents
dracula	Iconic Dracula purple & cyan palette
gruvbox	Earthy retro Gruvbox amber & warm brown tones
tokyo-night	Sleek Tokyo Night deep navy & vibrant cyan
monokai	Classic Monokai bright magenta & green accents

---

⌨️ 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
d / D	DELETE highlighted app — opens Really delete? [Y] Yes / [N] No popup; Y uninstalls, N/Esc returns
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 advanced search input (supports @source, >100M, protected:true)
Tab / Shift+Tab	Cycle specific source filter dropdown (pacman, aur, flatpak, etc.)
Enter	Stage selected applications and open full confirmation preview modal (Enter again to confirm)
c	In History modal: clear audit log / In main table: quick purge for cache
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 customize your visual palette, icon rendering mode, and register protected components:

# Visual theme palette: cyan, catppuccin, nord, dracula, gruvbox, tokyo-night, monokai
theme: catppuccin

# Icon glyph set: auto (default), nerd, unicode, or ascii
# - auto: uses Nerd Fonts unless running in a raw Linux console (TTY) or dumb terminal
# - nerd: always use full Nerd Font symbols (e.g. 󰮯, , , )
# - unicode: standard universal Unicode symbols (e.g. ◎, ▲, ◆, ▣, ✓, ✗)
# - ascii: pure ASCII text labels with zero font requirements (e.g. [pac], [aur], [v], [x])
icons: auto

# 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, orphans, cache, history, tui)
├── internal/
│   ├── model/            # Data types: AppInfo, RemovableFiles, Config, SourceMeta
│   ├── detector/         # Parallel detector engine (17+ 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 with theme engine
├── aur/                  # Arch User Repository (AUR) PKGBUILD definitions
├── 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 & Completions)

# 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.

Documentation

Overview

Package main provides the entry point and CLI commands for VEET.

VEET (Universal Linux App Uninstaller & Deep-Clean Residual Purger) is a modern, zero-latency terminal user interface (TUI) and headless CLI utility for Linux. It aggregates installed software across 15+ package managers, universal container formats, portable AppImages, and language toolchains, staging each candidate residual path (~/.config, ~/.cache, ~/.local/share, /etc, /var/log) for user inspection before performing atomic removals with batched privilege elevation.

Installation:

go install github.com/swadhinbiswas/veet@latest

Usage:

veet         # Launch interactive terminal UI (default)
veet scan    # List all installed applications across all package managers
veet scan --json # Output machine-readable JSON inventory
veet clean <app> # Deep-clean uninstall an application with staged preview