arrgo

Unified media automation in Go. A single, coherent replacement for the *arr stack.

Disclaimer

This is a learning experiment to see how well LLM agent harnesses could take an existing, complex software stack that grew organically over a decade+ and re-architect / re-implement it from scratch.

I'm leaving this "public" on GitHub as a learning asset. For the love of god don't try using it yourself.

Status

Early development — core features working, API and CLI functional.

Goals

• One system instead of 6+ services
• Three binaries: arrgod (server), arrgo (CLI), helm (TUI)
• Embedded SQLite database
• Single config file (TOML)
• Clean API design with Radarr/Sonarr compatibility shim for Overseerr
• Plex integration for library management and scanning

Quick Start

# Build (requires Go 1.24+ and task)
task build          # Build arrgo CLI and arrgod server
task build:helm     # Build helm TUI
task build:clients  # Build all clients (arrgo + helm)

# Initialize configuration - 1st run setup
./arrgo init

# Start server daemon
./arrgod

# Use the CLI (in another terminal)
./arrgo status
./arrgo search "The Matrix"

# Or use the TUI
./helm/helm

Configuration

Copy config.example.toml to config.toml and edit:

cp config.example.toml config.toml

Environment variables can be referenced with ${VAR_NAME} syntax.

CLI Commands

# Server daemon
arrgod                   # Start API server + background jobs
arrgod --config FILE     # Use custom config file

# System status
arrgo status             # Dashboard (connections, downloads, library)
arrgo status --verify    # Verify all downloads against clients/filesystem/Plex
arrgo status 42          # Verify specific download

# Downloads
arrgo downloads                     # Show active downloads
arrgo downloads --all               # Include terminal states (cleaned, failed)
arrgo downloads -s failed           # Filter by state
arrgo downloads show 42             # Show detailed download info
arrgo downloads cancel 42           # Cancel a download
arrgo downloads cancel 42 --delete  # Cancel and delete files
arrgo downloads retry 42            # Retry a failed download

# Library management
arrgo library list                           # List all tracked content
arrgo library delete 42                      # Remove content from library
arrgo library check                          # Verify files exist and Plex awareness
arrgo library import --from-plex Movies      # Import existing Plex library
arrgo library import --from-plex Movies --dry-run  # Preview import

# Search and grab
arrgo search "Movie"              # Search indexers for releases
arrgo search -v "Movie"           # Verbose (show indexer, group, service)
arrgo search "Movie" --grab best  # Auto-grab best result
arrgo search "Movie" --grab 1     # Grab specific result by number

# Import content
arrgo import list                            # Show pending imports
arrgo import 42                              # Import tracked download by ID
arrgo import --manual "/path/to/file.mkv"    # Import file with auto-parsed metadata
arrgo import --manual "/path" --dry-run      # Preview without changes

# Plex integration
arrgo plex status        # Show Plex connection and libraries
arrgo plex list movies   # List library contents with tracking status
arrgo plex search "Matrix"  # Search Plex
arrgo plex scan movies   # Trigger library scan

# Local commands (no server needed)
arrgo parse "Release.Name.2024.1080p.mkv"  # Parse release name
arrgo init               # Interactive setup wizard
arrgo version            # Print version

# Global flags
--json                   # Output as JSON
--quiet, -q              # Suppress non-essential output
--server URL             # Custom server URL (default: http://localhost:8484)

Architecture

┌──────────┐      ┌───────────────────────────────────────────────┐
│  arrgo   │ HTTP │                    arrgod                     │
│  (CLI)   │─────▶│  ┌─────────┐ ┌─────────┐ ┌─────────────────┐  │
├──────────┤      │  │ Library │ │ Search  │ │  Event-Driven   │  │
│  helm    │      │  └─────────┘ └─────────┘ │    Pipeline     │  │
│  (TUI)   │      │                          │ ┌─────────────┐ │  │
└──────────┘      │  ┌─────────────────────┐ │ │  Handlers   │ │  │
                  │  │      REST API       │ │ │  (download, │ │  │
                  │  │  /api/v1 + /api/v3  │ │ │  import,    │ │  │
                  │  └─────────────────────┘ │ │  cleanup)   │ │  │
                  │                          │ └─────────────┘ │  │
                  │  ┌─────────────────────┐ │ ┌─────────────┐ │  │
                  │  │       SQLite        │ │ │  Adapters   │ │  │
                  │  │ (content, events)   │ │ │ (SABnzbd,   │ │  │
                  │  └─────────────────────┘ │ │  qBit,Plex) │ │  │
                  │                          │ └─────────────┘ │  │
                  │                          └─────────────────┘  │
                  └───────────────────────────────────────────────┘
                          │            │           │          │
                     ┌────▼────┐  ┌────▼────┐ ┌────▼────┐┌────▼────┐
                     │Indexers │  │SABnzbd  │ │qBittor- ││  Plex   │
                     │Newznab/ │  │         │ │rent     │└─────────┘
                     │Torznab  │  └─────────┘ └─────────┘
                     └─────────┘

The download pipeline uses an event-driven architecture with Go channels and SQLite persistence. Events flow through handlers (download → import → cleanup) with adapters polling external systems and emitting state change events.

External Dependencies

• Usenet indexers — Direct Newznab support (NZBgeek, DrunkenSlug, etc.)
• Torrent indexers — Torznab support (via Prowlarr)
• SABnzbd — Usenet downloads
• qBittorrent — Torrent downloads
• Plex — Media server integration
• Overseerr — Request management (optional, via compat API)