pkg-ui

A cross-distro Linux package search tool with a beautiful TUI, built with Go.

Features

• 🔍 Search packages across multiple Linux distributions simultaneously
• 🐳 Docker-based containers for isolated package manager access
• ✨ Fuzzy matching for better search results
• 🎨 Beautiful terminal UI built with Bubble Tea
  • Modal interface with Normal/Search modes (vim-style)
  • Tab system to switch between distros
  • Split-pane layout with package info panel
  • Package details showing version, description, and more
  • Colorized output with clear visual hierarchy
• ⚡ Concurrent searches for fast results
• 🎯 Highly configurable via YAML
• 📁 Auto-creates config in ~/.config/pkg-ui/ on first run

Installation

go build -o pkg-ui .

Configuration

On first run, pkg-ui will automatically create a default configuration file at ~/.config/pkg-ui/config.yaml with all distros commented out.

Edit this file to enable the distros you want to search:

distros:
  - name: ubuntu
    image: ubuntu:22.04
    update_cmd: apt-get update
    search_cmd: apt-cache search --names-only {query}
    search_parser: lines

  - name: alpine
    image: alpine:latest
    update_cmd: apk update
    search_cmd: apk search {query}
    search_parser: lines

  - name: fedora
    image: fedora:39
    update_cmd: dnf makecache
    search_cmd: dnf list --quiet --available '*{query}*'
    search_parser: lines

  - name: arch
    image: archlinux:latest
    update_cmd: pacman -Sy
    search_cmd: pacman -Ss {query}
    search_parser: arch

Supported parsers:

• lines - For package managers that output one package per line (apt, apk, dnf)
• arch - For Arch Linux pacman format (handles multi-line output with descriptions)

See config.example.yaml for more examples.

Usage

Initialize Containers

Before searching, initialize the containers and update package indexes:

./pkg-ui init

This creates persistent Docker containers and updates their package databases.

CLI Search

Basic search:

./pkg-ui search curl

Fuzzy search with scoring:

./pkg-ui search --fuzzy curl

Limit results:

./pkg-ui search --limit 20 git

Show all results:

./pkg-ui search --limit 0 python

TUI Mode

Launch the interactive TUI:

./pkg-ui tui

With fuzzy matching:

./pkg-ui tui --fuzzy

TUI Features

• Split-Pane Layout: Package list on the left (60%), info panel on the right (40%)
• Package Info Panel: Shows detailed information for selected package:
  • Package name (bold, underlined)
  • Version number
  • Distribution name
  • Fuzzy match score (if enabled)
  • Full description (word-wrapped)
• Tab System: Each distro gets its own tab showing package count
• Mode Indicator: Visual indicator showing NORMAL or SEARCH mode
• Live Search: Type / to enter search mode, type your query, press Enter
• Vim Keybindings: h/j/k/l for navigation, g/G for top/bottom
• Color Coded:
  • Cyan border around info panel
  • Green highlight for selected item
  • Cyan for package names
  • Yellow for fuzzy match scores and labels
  • Active tab is bright green, inactive tabs are gray

TUI Modes

The TUI has two modes:

Normal Mode (default):

• / or ? - Enter search mode
• h or ← - Previous distro tab
• l or → or Tab - Next distro tab
• Shift+Tab - Previous distro tab
• j or ↓ - Move down in results
• k or ↑ - Move up in results
• g - Jump to top
• G - Jump to bottom
• Ctrl+d - Scroll down half page
• Ctrl+u - Scroll up half page
• q or Esc - Quit

Search Mode (activated with /):

• Type to enter search query
• Enter - Execute search and return to normal mode
• Esc - Cancel and return to normal mode
• Backspace - Delete character
• Ctrl+w - Delete last word
• Ctrl+u - Clear entire input

Environment Variables

• PKG_UI_CONFIG - Path to config file (default: config.yaml)

Architecture

pkg-ui/
├── internal/
│   ├── config/     # YAML configuration loading
│   ├── docker/     # Container lifecycle management
│   ├── search/     # Search execution & parsing
│   └── tui/        # Bubble Tea TUI
└── main.go         # CLI entrypoint

How It Works

1. Config-driven: All distros, images, and commands come from YAML config
2. Persistent containers: Uses docker run with sleep infinity, then docker exec
3. No hardcoding: Package manager commands are fully configurable
4. Fuzzy matching: Local Go-based fuzzy search using sahilm/fuzzy
5. Concurrent: Searches all distros in parallel with goroutines

Requirements

• Docker installed and running
• Go 1.20+ (for building)

Examples

Search for curl across all distros:

$ ./pkg-ui search curl
Searching for curl across 5 distros

Found 156 package(s) in 342ms

[ubuntu] 42 result(s)
  • curl
  • libcurl4
  • python3-curl
  ...

Fuzzy search with scores:

$ ./pkg-ui search --fuzzy git
Searching for git across 5 distros (fuzzy matching enabled)

Found 487 package(s) in 298ms

[alpine] 174 result(s)
  • git (score: 20)
  • gitg (score: 23)
  • gitea (score: 18)
  ...

License

MIT