shell/tui/README.md

📁 Backup File Browser TUI

A modern, interactive Terminal User Interface (TUI) for browsing and viewing backup files and logs in your shell environment. Built with Go and Charm's Bubble Tea framework for a delightful file exploration experience. This TUI provides read-only access to your backup infrastructure, allowing you to explore backup directories, view file details, and browse operation logs without modifying any files.

⌨️ Key Bindings

Navigation & File Browsing

Key	Action	Description
↑/k	Move up in list	Navigate backup services
↓/j	Move down in list	Navigate backup services
←/h	Move left (panel navigation)	Switch to service list panel
→/l	Move right (panel navigation)	Switch to output panel
Tab	Switch between panels	Toggle between service list and output
Enter	Browse selected directory	View backup files and details

View Management

Key	Action	Description
v	View backup logs	Switch to logs view
s	View backup status	Display backup file status information
f	View configuration	Show system and service configuration
r	Refresh current view	Reload directory and status information
Esc	Return to main view	Go back to main backup selection

Interface Control

Key	Action	Description
c	Clear output panel	Clear the output display area
?	Toggle help	Show/hide comprehensive help information
q/Ctrl+C	Quit application	Exit the TUI application

🚀 Features

📁 File Browser Interface

• Directory Navigation: Browse backup directories for different services
• File Details: View file sizes, modification dates, and backup types
• Service Organization: Organized by backup service (Plex, Immich, Media services, etc.)
• Log File Viewing: Browse and read backup operation logs

📊 Information Display

• Backup Statistics: View file counts, total sizes, and backup ages
• Status Information: Display backup directory health and availability
• Configuration Details: Show system and service configuration information
• File Metadata: Display compressed file status and service associations

🖥️ User Interface

• Dual-panel System: Service list and detailed information viewer
• Multiple View Modes: Main browser, logs viewer, status, and configuration views
• Tab Navigation: Switch between panels with Tab key
• Smart Key Bindings: Intuitive keyboard shortcuts for navigation
• Color-coded Display: Dynamic visual indicators for file types and status
• Context-sensitive Information: Detailed descriptions for each backup service

📦 Backup Service Directories

• 🔵 Plex Backups: Browse Plex Media Server backup files and archives
• 🖼️ Immich Backups: View Immich photo management backup files
• 🎬 Media Services: Browse Sonarr, Radarr, Prowlarr, and other media service backups
• 🔧 Environment Files: View Docker environment and configuration file backups
• 🐳 Docker Configuration: Browse container and compose file backups
• 📊 Tautulli: Browse Plex statistics and monitoring backups
• 📚 Audiobookshelf: View audiobook server backup files
• 📥 SABnzbd: Browse download client configuration backups
• 🎯 Jellyseerr: View request management system backups

📋 Log and Status Viewing

• Backup History: Browse historical backup operation logs
• File Information: View detailed file metadata and timestamps
• Directory Statistics: See backup counts, sizes, and dates
• System Configuration: Display current system and service settings

🎯 Quick Start

Installation

The TUI uses a consistent build system with multiple options:

# Option 1: Use the launcher script (recommended)
cd /home/acedanger/shell
./launch-backup-tui.sh

# Option 2: Use Makefile for development
cd tui
make all          # Build and install
make build        # Build only
make dev          # Quick development build

# Option 3: Use build script
cd tui
./build.sh

# Option 4: Direct Go build
cd tui
go build -o backup-tui main.go

First Time Setup

1. Ensure Go 1.19+ is installed (only needed for rebuilding)
2. Navigate to your shell directory where backup scripts are located
3. Launch the TUI using ./launch-backup-tui.sh
4. Use arrow keys or hjkl to navigate the interface
5. Press ? for comprehensive help and key bindings

Launch the TUI

# From the shell directory (recommended - auto-builds if needed)
./launch-backup-tui.sh

# Or if binary exists
./backup-tui

# Or from the tui directory
cd tui && ./backup-tui

Key Bindings

Key	Action
↑/k	Move up in list
↓/j	Move down in list
←/h	Move left (panel navigation)
→/l	Move right (panel navigation)
Enter	Browse selected directory
Tab	Switch between panels
v	View backup logs
s	View backup status
f	View configuration
x	Return to main view
c	Clear output panel
Esc	Return to main view
?	Toggle help
q/Ctrl+C	Quit application

📁 Available Backup Directories

Backup Service Directories

1. 📦 Plex Backups - Browse Plex Media Server backup archives and files
2. 🖼️ Immich Backups - View Immich photo management backup files
3. 🎬 Sonarr Backups - Browse Sonarr TV series management backup files
4. 🎭 Radarr Backups - View Radarr movie management backup files
5. 🔍 Prowlarr Backups - Browse Prowlarr indexer management backup files
6. 🎯 Jellyseerr Backups - View Jellyseerr request management backup files
7. 📥 SABnzbd Backups - Browse SABnzbd download client backup files
8. 📊 Tautulli Backups - View Tautulli Plex statistics backup files
9. 📚 Audiobookshelf Backups - Browse Audiobookshelf server backup files
10. 🐳 Docker Data Backups - View Docker container data and volume backups
11. 📋 Backup Logs - Browse backup operation logs and history

Directory Information

Each directory shows:

• File listings with names, sizes, and modification dates
• Directory statistics including total files and combined size
• Backup metadata such as compression status and service type
• Path information for easy navigation and reference

🔧 How It Works

Directory Structure Detection

The TUI automatically discovers and organizes backup directories:

• Backup Path: Scans /mnt/share/media/backups/ for service directories
• Service Recognition: Identifies Plex, Immich, media services, and other backup folders
• File Analysis: Reads file metadata including sizes, dates, and compression status
• Log Discovery: Locates and organizes backup operation log files

File Browsing System

• Directory Navigation: Browse through backup files organized by service
• File Details: Display comprehensive file information and metadata
• Content Organization: Sort files by date, size, or modification time
• Path Tracking: Maintain breadcrumb navigation for easy orientation

Log File Integration

• Log File Reading: Access backup operation logs from logs/ directories
• Date Parsing: Extract timestamps and service information from log filenames
• Content Display: Show log contents with proper formatting and navigation
• Historical Viewing: Browse logs by date and service for troubleshooting

🎨 Interface Layout

┌─── 📁 Backup File Browser ────────────┐
│┌─────────────── Services ──────────────┐┌─── File Details ────┐│
││> 1. 📦 Plex Backups                   ││📦 Plex Backups      ││
││  2. 🖼️ Immich Backups                 ││                     ││
││  3. 🎬 Sonarr Backups                 ││Files: 15            ││
││  4. 🎭 Radarr Backups                 ││Size: 2.3 GB         ││
││  5. 🔍 Prowlarr Backups               ││Last: 2024-01-15     ││
│└───────────────────────────────────────┘└─────────────────────┘│
│View: MAIN | Panel: Backup List | Path: /mnt/share/media/backups │
└──────────────────────────────────────────────────────────────────┘

🔨 Development

Prerequisites

• Go 1.19+ installed
• Access to backup scripts in the shell environment
• Terminal with at least 80x24 resolution

Building from Source

The TUI includes multiple build options for consistent binary naming:

# Option 1: Use Makefile (recommended for development)
cd tui
make all          # Clean, build, and install
make build        # Build only
make dev          # Quick development build
make clean        # Remove build artifacts
make help         # Show all targets

# Option 2: Use build script
cd tui
./build.sh

# Option 3: Direct Go build
cd tui
export GOROOT=/usr/lib/go-1.19
export PATH=$PATH:$GOROOT/bin
go mod tidy
go build -o backup-tui main.go

Binary Naming: All build methods consistently create backup-tui binary.

Dependencies

• Bubble Tea - TUI framework
• Bubbles - TUI components
• Lipgloss - Styling

📊 Status Indicators

Icon	Status	Description
✅	Available	Directory exists and contains backup files
❌	Missing	Directory path not found or inaccessible
📁	Directory	Backup service directory with file contents
📋	Logs	Log files and backup operation history

🚀 Advanced Usage

File Browsing Features

The TUI provides comprehensive backup file exploration:

• Directory Exploration: Browse backup files organized by service type
• File Filtering: Navigate through files by date, size, or service
• Metadata Display: View detailed file information including compression status

Backup Analysis

• Size Tracking: Monitor backup file sizes and storage usage
• Date Analysis: Review backup frequency and file modification dates
• Service Organization: Files organized by backup service for easy navigation
• Compression Detection: Identify compressed archives and their contents

Log File Management

• Log Browsing: Navigate through backup operation logs by date and service
• Content Viewing: Read log file contents directly within the TUI
• Error Investigation: Quickly locate and review backup operation issues
• Historical Analysis: Track backup patterns and success rates over time

🔗 Integration

Existing Workflow

The TUI complements your existing backup infrastructure:

• Read-Only Access: Safely browse backup files without risk of modification
• Log Integration: View backup operation logs from existing automation
• Directory Monitoring: Track backup file creation and organization
• Compatible Viewing: Works alongside existing backup scripts and cron jobs

Backup Infrastructure Viewing

• File Discovery: Automatically detects backup files from all services
• Status Information: Shows backup file health and availability
• Log Analysis: Provides easy access to backup operation history
• Storage Monitoring: Track backup storage usage and file organization

📝 Notes

• The TUI automatically detects backup directory structure and organization
• Provides read-only access to backup files for safe browsing and analysis
• Backup files are displayed with metadata including sizes, dates, and compression status
• Log files can be viewed directly within the interface for troubleshooting and analysis

---

Built with ❤️ using Charm tools for a delightful terminal experience!