shell/tui/README.md

🔧 Enhanced Backup Manager TUI

A modern, interactive Terminal User Interface (TUI) for## ⌨️ Enhanced Key Bindings

Navigation & Control

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/Space	Execute selected backup	Start the selected backup operation

View Management

Key	Action	Description
v	View backup logs	Switch to logs view with real-time updates
s	View backup status	Display comprehensive status dashboard
c	View configuration	Show system and service configuration
r	Refresh status and logs	Reload all status information
Esc	Return to main view	Go back to main backup selection

Process Control

Key	Action	Description
x	Stop running backup	Gracefully cancel active backup process
Space	Clear output panel	Clear the output display area
?	Toggle help	Show/hide comprehensive help information
q/Ctrl+C	Quit application	Exit the TUI application

Advanced Features

Key	Action	Description
f	View configuration	Detailed system and service information
p	Progress details	Show detailed progress metrics
l	Live logs	Real-time log streaming display

🚀 Enhanced Features

📊 Real-time Progress Tracking

• Visual Progress Bars: Live progress indicators with percentage display
• ETA Calculations: Intelligent time estimation based on current progress
• Output Streaming: Real-time display of backup command output
• Performance Metrics: Elapsed time tracking and transfer statistics

🎛️ Advanced Process Management

• Context Cancellation: Graceful backup cancellation with context support
• Process Monitoring: Track and control multiple simultaneous backups
• Resource Management: Memory-safe output handling with line limits
• Thread Safety: Concurrent operation support with proper synchronization

🖥️ Enhanced User Interface

• Dual-panel System: Service list and live output viewer
• Multiple View Modes: Main, logs, status, and configuration views
• Tab Navigation: Switch between panels with Tab key
• Smart Key Bindings: Intuitive keyboard shortcuts for all actions
• Color-coded Status: Dynamic status indicators with real-time updates
• Progressive Disclosure: Context-sensitive information display

📦 Integrated Backup Services

• 🔵 Plex Backup: Complete Plex Media Server backup with integrity checking
• 🖼️ Immich Backup: Database and uploads backup with B2 cloud sync
• 🎬 Media Services: Sonarr, Radarr, Prowlarr, and other media services backup
• 🔧 Environment Files: Docker environment and configuration files backup
• 🐳 Docker Configuration: Container and compose files backup

✅ Validation & Monitoring

• Backup Validation: Integrity checking for all backup types
• Real-time Monitoring: Live backup status and progress tracking
• Health Checks: Comprehensive backup health monitoring
• Status Dashboard: Detailed status view with statistics and summaries

🔄 Restoration Services

• Safe Restoration: Validated restoration with dry-run options
• Current Data Backup: Automatic backup before restoration
• Interactive Selection: Choose from available backup files

🛡️ Intelligent Error Handling

• Comprehensive Error Tracking: Detailed error analysis and reporting
• User-friendly Messages: Clear error descriptions with context
• Recovery Suggestions: Automated recommendations for error resolution
• Graceful Degradation: Continues operation when individual components fail

🎯 Quick Start

Installation

The TUI is already built and ready to use! Simply run:

# From the shell directory
./backup-tui

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

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 ./backup-tui
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
./backup-tui

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

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/Space	Execute selected backup
Tab	Switch between panels
v	View backup logs
s	View backup status
f	View configuration
r	Refresh status and logs
x	Stop running backup
c	Clear output panel
Esc	Return to main view
?	Toggle help
q/Ctrl+C	Quit application

📋 Available Operations

Core Backup Operations

1. 📦 Plex Backup - Enhanced backup with integrity verification
2. 🖼️ Immich Backup - Complete database and media backup
3. 🎬 Media Services Backup - All media service configurations
4. 🔧 Environment Files Backup - Docker environment files
5. 🐳 Docker Configuration Backup - Container configurations

Validation Services

1. ✅ Validate Plex Backups - Check Plex backup integrity
2. ✅ Validate Immich Backups - Verify Immich backups
3. ✅ Validate Environment Backups - Check environment backup health

Monitoring & Status

1. 📊 Monitor Plex Status - Real-time Plex backup monitoring

Restoration Services

1. 🔄 Restore Plex - Safe Plex restoration with validation
2. 🔄 Restore Immich - Immich restoration from backup

🔧 How It Works

Script Integration

The TUI integrates with your existing backup scripts:

• Plex Scripts: plex/backup-plex.sh, plex/restore-plex.sh, etc.
• Immich Scripts: immich/backup-immich.sh, immich/restore-immich.sh, etc.
• Media Scripts: backup-media.sh, backup-env-files.sh, etc.

Real-time Execution

• Scripts are executed with appropriate arguments
• Output is captured and displayed in real-time
• Status is tracked and updated live
• Errors are handled gracefully with detailed reporting

Log Integration

• Reads from existing log files in logs/ directories
• Parses performance data from JSON logs
• Displays recent activity and status information
• Provides searchable log viewer

🎨 Interface Layout

┌─── 🔧 Media & Plex Backup Manager ────┐
│┌─────────────── Services ──────────────┐┌─── Output / Logs ───┐│
││> 1. 📦 Plex Backup                    ││Running backup...     ││
││  2. 🖼️ Immich Backup                  ││                     ││
││  3. 🎬 Media Services Backup          ││Status: ✅ Success    ││
││  4. ✅ Validate Plex Backups          ││Duration: 45.3s      ││
││  5. 🔧 Environment Files Backup       ││                     ││
│└───────────────────────────────────────┘└─────────────────────┘│
│plex: ✅ 45.3s | immich: idle | Panel: Backup List               │
└──────────────────────────────────────────────────────────────────┘

🔨 Development

Prerequisites

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

Building from Source

cd tui
export GOROOT=/usr/lib/go-1.19
export PATH=$PATH:$GOROOT/bin
go mod tidy
go build -o backup-manager main.go

Dependencies

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

📊 Status Indicators

Icon	Status	Description
✅	Success	Operation completed successfully
❌	Error	Operation failed with errors
🔄	Running	Operation currently in progress
⏸️	Idle	Service available but not running

🚀 Advanced Usage

Automated Operations

The TUI integrates with your existing automation:

• Cron jobs continue to work independently
• TUI provides manual execution and monitoring
• Status reflects both manual and automated runs

Script Arguments

• Backup scripts are called with appropriate flags (--non-interactive, etc.)
• Restore operations use safe defaults (--dry-run for Plex)
• Validation scripts run with comprehensive checks

Log Management

• View recent logs with v key
• Logs are sorted by timestamp (newest first)
• Real-time updates when logs change
• Integration with existing logging infrastructure

🔗 Integration

Existing Workflow

The TUI complements your existing backup infrastructure:

• Preserves all existing scripts and functionality
• Enhances with interactive management
• Integrates with current logging and monitoring
• Maintains compatibility with automation

Notification Integration

• Scripts continue to send notifications (webhook, email)
• TUI provides additional visual feedback
• Status updates reflect script execution results
• Status updates reflect script execution results

📝 Notes

• The TUI automatically detects the shell directory structure
• Scripts are executed from their proper directories
• Environment variables and paths are preserved
• Safe execution with proper error handling

---

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