clawarr-suite

What this skill does

# ClawARR Suite

Unified deep-integration control for self-hosted media automation stacks. This skill provides comprehensive agent-executable operations across the entire *arr ecosystem with rich analytics, dashboard generation, and advanced library exploration.

## Security & Scanner Clarity

- Local-first operations: all API calls target user-provided local hosts (typically LAN/NAS).
- No embedded secrets: API keys/tokens are sourced from environment variables or user-owned config files.
- No telemetry/exfiltration paths: scripts do not transmit credentials or library data to third-party endpoints.
- Destructive behavior is opt-in: delete/remove actions require explicit command invocation by the user/agent.
- Setup logic avoids dynamic `eval` and uses explicit variable mapping for scanner-friendly shell behavior.

## Quick Start

**First time setup (recommended):**
```bash
scripts/setup.sh <host-ip-or-hostname>
```
Discovers services, grabs API keys, verifies connections, and outputs your config.

**Common operations:**
```bash
scripts/status.sh              # Health check all services
scripts/library.sh stats all   # Library statistics
scripts/analytics.sh activity  # Current Plex streams
scripts/dashboard.sh           # Generate HTML dashboard
scripts/manage.sh wanted all   # Show missing content
scripts/requests.sh list       # Overseerr requests
```

## Scripts Overview

### Core Operations
- **`setup.sh`** — Guided setup wizard with auto-discovery
- **`discover.sh`** — Scan host for *arr services
- **`status.sh`** — Health check all configured services
- **`diagnose.sh`** — Automated troubleshooting

### Library Exploration (`library.sh`)
Deep statistics and exploration for Radarr/Sonarr/Lidarr:
```bash
library.sh stats [app]          # Overall library stats
library.sh quality [app]        # Quality profile breakdown
library.sh missing [app]        # Missing/wanted content
library.sh unmonitored [app]    # Unmonitored items
library.sh recent [app] [days]  # Recently added (default: 7)
library.sh genres [app]         # Genre distribution
library.sh years [app]          # Year distribution
library.sh studios [app]        # Studio/network breakdown
library.sh nofiles [app]        # Monitored but no files
library.sh disk [app]           # Disk usage by root folder
```

### Analytics (`analytics.sh`)
Rich viewing analytics from Tautulli/Plex:
```bash
analytics.sh activity                 # Currently watching
analytics.sh history [count]          # Watch history
analytics.sh most-watched [period]    # Most watched (week/month/year)
analytics.sh popular-genres [period]  # Popular genres
analytics.sh peak-hours               # Peak watching hours
analytics.sh user-stats [user]        # User activity
analytics.sh library-stats            # Plex library stats
analytics.sh recent-added [count]     # Recently added to Plex
analytics.sh play-totals              # Total play statistics
```

### Content Management (`manage.sh`)
Add, remove, and manage content:
```bash
manage.sh add-movie "<title>" [quality] [root]
manage.sh add-series "<title>" [quality] [root]
manage.sh remove <app> <id>
manage.sh wanted [app]
manage.sh calendar [app] [days]
manage.sh history [app] [count]
manage.sh rename <app> <id>
manage.sh refresh <app> [id]
```

### Request Management (`requests.sh`)
Overseerr request handling:
```bash
requests.sh list [pending|approved|available|all]
requests.sh approve <id>
requests.sh deny <id> [reason]
requests.sh info <id>
requests.sh stats
```

### Subtitle Management (`subtitles.sh`)
Bazarr operations:
```bash
subtitles.sh wanted
subtitles.sh history [count]
subtitles.sh search <series|movie> <id>
subtitles.sh languages
```

### Indexer Management (`indexers.sh`)
Prowlarr operations:
```bash
indexers.sh list
indexers.sh test [id]
indexers.sh stats
```

### Download Client (`downloads.sh`)
SABnzbd operations:
```bash
downloads.sh active
downloads.sh speed
downloads.sh history [count]
downloads.sh pause
downloads.sh resume
downloads.sh queue
```

### Dashboard Generation (`dashboard.sh`)
Generate self-contained HTML dashboard:
```bash
dashboard.sh [output_file]
```
Creates beautiful dark-themed dashboard with:
- System health
- Download activity
- Library statistics
- Recent activity
- Viewing analytics
- Disk usage

Output defaults to `clawarr-dashboard.html` (open in any browser).

### Media Tracker Integration (`trakt.sh`, `trackers.sh`, `letterboxd.sh`, `simkl.sh`)

Track and sync what you watch across services like Trakt.tv, Letterboxd, Simkl, and more.

**Unified Interface (`trackers.sh`):**
```bash
trackers.sh setup              # Interactive setup wizard
trackers.sh status             # Show configured trackers
trackers.sh sync plex trakt    # Sync Plex → Trakt
trackers.sh export trakt json  # Export watch history
trackers.sh import letterboxd file.csv
trackers.sh compare trakt simkl
```

**Trakt.tv Integration (`trakt.sh`):**

*Authentication:*
```bash
trakt.sh auth                  # Device code OAuth flow
trakt.sh auth-status           # Check authentication
```

*Profile & Stats:*
```bash
trakt.sh profile [username]    # Show profile
trakt.sh stats [username]      # Detailed statistics
```

*Watching & History:*
```bash
trakt.sh watching              # Currently watching
trakt.sh history [movies|shows|episodes] [limit]
trakt.sh sync-history export file.json
trakt.sh sync-history import file.json
```

*Scrobbling:*
```bash
trakt.sh scrobble start movie 12345
trakt.sh scrobble stop movie 12345 100
trakt.sh checkin movie "Inception"
```

*Lists & Collections:*
```bash
trakt.sh watchlist [movies|shows]
trakt.sh watchlist-add movie "Dune Part Two"
trakt.sh collection movies
trakt.sh collection-add movie 12345
trakt.sh lists                 # Custom lists
trakt.sh list-items my-favorites
```

*Ratings:*
```bash
trakt.sh ratings movies 8      # Movies rated 8+
trakt.sh rate movie "Inception" 10
```

*Discovery:*
```bash
trakt.sh recommendations movies
trakt.sh trending shows
trakt.sh popular movies
trakt.sh calendar all 7        # Next 7 days
```

*Search:*
```bash
trakt.sh search "Breaking Bad" show
```

*Sync:*
```bash
trakt.sh sync-plex             # Sync Plex watch history to Trakt
```

**Letterboxd Integration (`letterboxd.sh`):**
```bash
letterboxd.sh export           # Export from Plex as Letterboxd CSV
letterboxd.sh import diary.csv # Import Letterboxd diary
letterboxd.sh profile username # View public profile
letterboxd.sh diary username 2024
```

**Simkl Integration (`simkl.sh`):**
```bash
simkl.sh auth                  # OAuth authentication
simkl.sh profile               # Show profile
simkl.sh stats                 # Viewing statistics
simkl.sh history movies        # Watch history
simkl.sh watchlist all         # View watchlist
simkl.sh sync                  # Sync with Plex
```

### Traktarr & Retraktarr Integration

Automate content discovery and library syncing with Trakt lists.

**Traktarr (Trakt → Radarr/Sonarr):**
```bash
# Status and configuration
trakt.sh traktarr-status       # Check if installed
trakt.sh traktarr-config       # Configure Traktarr

# Add content from Trakt lists
trakt.sh traktarr-add movies trending 10
trakt.sh traktarr-add movies anticipated 15
trakt.sh traktarr-add movies popular 5
trakt.sh traktarr-add shows trending 5
trakt.sh traktarr-add movies watchlist 50
```

**Retraktarr (Radarr/Sonarr → Trakt):**
```bash
# Status and configuration
trakt.sh retraktarr-status     # Check if installed
trakt.sh retraktarr-config     # Configure Retraktarr

# Sync library to Trakt lists
trakt.sh retraktarr-sync all   # Sync movies and shows
trakt.sh retraktarr-sync movies
trakt.sh retraktarr-sync shows
```

**Installation via Setup Wizard:**
```bash
trackers.sh setup
# Choose option 5 for Traktarr
# Choose option 6 for Retraktarr
# Offers to install via pip if not found
```

**What They Do:**
- **Traktarr:** Automatically adds content from Trakt lists (trending, anticipated, watchlist, custom) to Radarr/Sonarr