Clawarr Suite

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):

scripts/setup.sh <host-ip-or-hostname>

Discovers services, grabs API keys, verifies connections, and outputs your config.

Common operations:

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:

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:

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:

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:

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:

subtitles.sh wanted
subtitles.sh history [count]
subtitles.sh search <series|movie> <id>
subtitles.sh languages

Indexer Management (indexers.sh)

Prowlarr operations:

indexers.sh list
indexers.sh test [id]
indexers.sh stats

Download Client (downloads.sh)

SABnzbd operations:

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:

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):

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:

trakt.sh auth                  # Device code OAuth flow
trakt.sh auth-status           # Check authentication

Profile & Stats:

trakt.sh profile [username]    # Show profile
trakt.sh stats [username]      # Detailed statistics

Watching & History:

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:

trakt.sh scrobble start movie 12345
trakt.sh scrobble stop movie 12345 100
trakt.sh checkin movie "Inception"

Lists & Collections:

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:

trakt.sh ratings movies 8      # Movies rated 8+
trakt.sh rate movie "Inception" 10

Discovery:

trakt.sh recommendations movies
trakt.sh trending shows
trakt.sh popular movies
trakt.sh calendar all 7        # Next 7 days

Search:

trakt.sh search "Breaking Bad" show

Sync:

trakt.sh sync-plex             # Sync Plex watch history to Trakt

Letterboxd Integration (letterboxd.sh):

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):

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):

# 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):

# 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:

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 for download
• Retraktarr: Syncs your Radarr/Sonarr library back to Trakt as public/private lists

See references/traktarr-retraktarr.md for complete setup, cron scheduling, and usage patterns.

Prowlarr Indexer Management (prowlarr.sh)

Centralized indexer management across all *arr apps:

prowlarr.sh indexers              # List all indexers
prowlarr.sh test [id]             # Test indexer(s)
prowlarr.sh stats                 # Indexer & app sync statistics
prowlarr.sh search <query> [type] # Search across all indexers (type: movie|tv|audio|book)
prowlarr.sh apps                  # List sync targets (Sonarr/Radarr/etc)
prowlarr.sh add-app <type> <url> <key>  # Add app sync target
prowlarr.sh sync                  # Trigger sync to all apps
prowlarr.sh status                # Health check
prowlarr.sh logs [count]          # Recent logs

Recyclarr Quality Profiles (recyclarr.sh)

Sync TRaSH Guides quality profiles to Sonarr/Radarr:

recyclarr.sh status               # Check status & config
recyclarr.sh sync [instance]      # Sync profiles (all or specific)
recyclarr.sh diff [instance]      # Preview changes without applying
recyclarr.sh profiles             # List available TRaSH profiles
recyclarr.sh qualities [app]      # List quality definitions
recyclarr.sh config               # Show current config
recyclarr.sh create-config        # Generate config template
recyclarr.sh logs [count]         # View recent logs

Maintainerr Library Cleanup (maintainerr.sh)

Automated library cleanup based on rules:

maintainerr.sh status             # Check status
maintainerr.sh rules              # List cleanup rules
maintainerr.sh collections        # List managed collections
maintainerr.sh run [rule_id]      # Trigger rules (all or specific)
maintainerr.sh media <rule_id>    # Show media matched by a rule
maintainerr.sh exclude <media_id> <rule_id>  # Exclude media from rule
maintainerr.sh logs               # View activity log

Notifiarr Notifications (notifiarr.sh)

Unified notification management across *arr services:

notifiarr.sh status               # Check status & integrations
notifiarr.sh triggers             # List notification triggers
notifiarr.sh services             # Show connected services
notifiarr.sh test [channel]       # Send test notification
notifiarr.sh config               # Configuration summary
notifiarr.sh logs                 # Recent notification log

Kometa Collection Manager (kometa.sh)

Plex collection, overlay, and metadata automation:

kometa.sh status                  # Check container status
kometa.sh run [library]           # Run Kometa (all or specific library)
kometa.sh collections             # Show Plex collections
kometa.sh overlays                # Check overlay config
kometa.sh config                  # Show Kometa config
kometa.sh templates               # List available default collections/overlays
kometa.sh logs [count]            # View recent logs

Unpackerr Archive Extraction (unpackerr.sh)

Automatic archive extraction for download clients:

unpackerr.sh status               # Check status & config
unpackerr.sh activity             # Recent extraction activity
unpackerr.sh errors               # Recent errors/warnings
unpackerr.sh config               # Show configuration
unpackerr.sh logs [count]         # View recent logs
unpackerr.sh restart              # Restart container

Legacy Scripts

• queue.sh — View download queues (use manage.sh wanted or downloads.sh active for more detail)
• search.sh — Search content (use manage.sh add-* for full workflow)

Configuration

Environment Variables

Core Services:

export CLAWARR_HOST=192.168.1.100
export SONARR_KEY=abc123...
export RADARR_KEY=def456...
export LIDARR_KEY=ghi789...
export READARR_KEY=jkl012...
export PROWLARR_KEY=mno345...
export BAZARR_KEY=pqr678...
export OVERSEERR_KEY=stu901...
export PLEX_TOKEN=vwx234...
export TAUTULLI_KEY=yz567...
export SABNZBD_KEY=abc890...
export NOTIFIARR_KEY=xyz123...

# Companion services (auto-detected, keys optional)
export PROWLARR_KEY=abc123...   # Required for prowlarr.sh

# Docker-based services (SSH access for remote management)
export RECYCLARR_SSH=mynas       # SSH host for recyclarr container
export KOMETA_SSH=mynas          # SSH host for kometa container
export UNPACKERR_SSH=mynas       # SSH host for unpackerr container
export DOCKER_CONFIG_BASE=/opt/docker  # Docker config root (default: /volume1/docker for Synology)

Media Trackers (optional):

# Trakt.tv (register app at https://trakt.tv/oauth/applications/new)
export TRAKT_CLIENT_ID=your_client_id
export TRAKT_CLIENT_SECRET=your_client_secret

# Simkl (register at https://simkl.com/settings/developer)
export SIMKL_CLIENT_ID=your_client_id
export SIMKL_CLIENT_SECRET=your_client_secret

# Letterboxd (requires API approval)
export LETTERBOXD_API_KEY=your_api_key  # Optional, uses CSV export if not set

Token Storage:

• Tokens are automatically saved to ~/.config/clawarr/
• Files: trakt_tokens.json, simkl_tokens.json
• Permissions: 600 (user read/write only)

Store in .env file and source before running scripts.

Standard Ports

• Sonarr: 8989
• Radarr: 7878
• Lidarr: 8686
• Readarr: 8787
• Prowlarr: 9696
• Bazarr: 6767
• Overseerr: 5055
• Plex: 32400
• Tautulli: 8181
• SABnzbd: 38080
• Notifiarr: 5454
• Maintainerr: 6246
• FlareSolverr: 8191
• Homarr: 7575

API Key Discovery

Method 1: /initialize.json (Easiest)

Most *arr apps expose API key at public endpoint:

curl -s http://HOST:7878/initialize.json | jq -r '.apiKey'

For older versions (v3):

curl -s http://HOST:7878/initialize.js | grep -o "apiKey: '[^']*'" | cut -d"'" -f2

Method 2: Config Files

Docker/Unraid/Synology: /config/config.xml (inside container)

grep '<ApiKey>' /path/to/config.xml | sed 's/.*<ApiKey>\(.*\)<\/ApiKey>.*/\1/'

Method 3: Web UI

Settings → General → Security → API Key

Plex Token

From Plex Web UI:

1. Open any media item
2. "Get Info" → "View XML"
3. URL contains X-Plex-Token=...

Or use:

curl -u "username:password" -X POST \
  'https://plex.tv/users/sign_in.json' \
  -H "X-Plex-Client-Identifier: <unique-id>"

Tautulli API Key

Settings → Web Interface → API → API Key

SABnzbd API Key

Config → General → Security → API Key

Common Workflows

Library Analysis

# Get complete library overview
scripts/library.sh stats all

# Find quality upgrade candidates
scripts/library.sh quality radarr

# Show missing content
scripts/library.sh missing all

# Check disk usage
scripts/library.sh disk all

Viewing Analytics

# Current activity
scripts/analytics.sh activity

# Most watched this month
scripts/analytics.sh most-watched month

# User statistics
scripts/analytics.sh user-stats

# Peak hours
scripts/analytics.sh peak-hours

Request Management

# Show pending requests
scripts/requests.sh list pending

# Approve request
scripts/requests.sh approve 123

# Request statistics
scripts/requests.sh stats

Content Management

# Add movie
scripts/manage.sh add-movie "Dune Part Two"

# Show calendar
scripts/manage.sh calendar all 7

# View history
scripts/manage.sh history radarr 30

# Show wanted/missing
scripts/manage.sh wanted all

Indexer Management (Prowlarr)

# List and test all indexers
scripts/prowlarr.sh indexers
scripts/prowlarr.sh test

# Search across all indexers
scripts/prowlarr.sh search "Dune" movie

# Add Sonarr/Radarr as sync targets
scripts/prowlarr.sh add-app sonarr http://host:8989 <sonarr_key>
scripts/prowlarr.sh add-app radarr http://host:7878 <radarr_key>

# Trigger indexer sync to all apps
scripts/prowlarr.sh sync

Quality Profiles (Recyclarr)

# Preview changes
scripts/recyclarr.sh diff

# Sync TRaSH Guides profiles
scripts/recyclarr.sh sync

# Check status
scripts/recyclarr.sh status

Library Cleanup (Maintainerr)

# View rules and matched media
scripts/maintainerr.sh rules
scripts/maintainerr.sh media 1

# Run cleanup
scripts/maintainerr.sh run

# Exclude something from cleanup
scripts/maintainerr.sh exclude 12345 1

Collections & Overlays (Kometa)

# Run collection/overlay generation
scripts/kometa.sh run

# View existing collections
scripts/kometa.sh collections

# See available templates
scripts/kometa.sh templates

Dashboard

# Generate dashboard
scripts/dashboard.sh my-dashboard.html

# Open in browser
open my-dashboard.html

Media Tracking Workflows

Initial Setup:

# Set up Trakt.tv
scripts/trackers.sh setup
# Select option 1 (Trakt.tv)
# Follow device auth flow

# Check status
scripts/trackers.sh status

Sync Plex to Trakt:

# One-time sync of watch history
scripts/trakt.sh sync-plex

# Or use unified interface
scripts/trackers.sh sync plex trakt

Export for Letterboxd:

# Generate Letterboxd-compatible CSV
scripts/letterboxd.sh export

# Upload at letterboxd.com/import/

Cross-Tracker Sync:

# Export from Trakt, convert for Letterboxd
scripts/trackers.sh sync trakt letterboxd

# Compare two services
scripts/trackers.sh compare trakt simkl

Discovery & Recommendations:

# Get personalized recommendations
scripts/trakt.sh recommendations movies

# See what's trending
scripts/trakt.sh trending shows

# Check upcoming releases
scripts/trakt.sh calendar all 7

Track Viewing:

# See what you're currently watching
scripts/trakt.sh watching

# View watch history
scripts/trakt.sh history movies 50

# Rate something you watched
scripts/trakt.sh rate movie "Inception" 10

Automation with Traktarr/Retraktarr:

# Set up Traktarr (Trakt → Arr)
scripts/trackers.sh setup  # Option 5

# Add trending movies to Radarr
scripts/trakt.sh traktarr-add movies trending 10

# Add anticipated shows to Sonarr
scripts/trakt.sh traktarr-add shows anticipated 5

# Set up Retraktarr (Arr → Trakt)
scripts/trackers.sh setup  # Option 6

# Sync library to Trakt lists
scripts/trakt.sh retraktarr-sync all

# Schedule automation (cron):
# Traktarr every 6 hours: 0 */6 * * * traktarr run
# Retraktarr daily at 3am: 0 3 * * * retraktarr sync

Troubleshooting

No Files Eligible for Import

Diagnosis:

scripts/diagnose.sh

Common causes:

1. Stale Docker mounts — Container restarted but host didn't
2. Path mapping — Download client and *arr app see different paths
3. Permissions — *arr app can't read download directory
4. Category mismatch — Download in wrong category

Solutions:

# Restart containers (fixes stale mounts)
docker restart radarr sonarr

# Check path mappings
# Settings → Download Clients → Remote Path Mappings

Queue Stuck

Check download client:

scripts/downloads.sh active
scripts/downloads.sh speed

*Check arr queues:

scripts/manage.sh wanted all

Check indexers:

scripts/indexers.sh test
scripts/indexers.sh stats

Missing Subtitles

scripts/subtitles.sh wanted
scripts/subtitles.sh search series <id>

Reference Documentation

• references/api-endpoints.md — Complete API reference for all services
• references/tracker-apis.md — Media tracker API documentation (Trakt, Simkl, Letterboxd)
• references/traktarr-retraktarr.md — Complete guide to Traktarr & Retraktarr automation
• references/companion-services.md — Prowlarr, Recyclarr, FlareSolverr, Unpackerr, Notifiarr, Maintainerr, Kometa reference
• references/common-issues.md — Troubleshooting guide with solutions
• references/setup-guide.md — Platform-specific installation
• references/prompts.md — Suggested natural-language prompts for agents
• references/dashboard-templates.md — HTML/CSS templates for dashboards

Example Agent Prompts

See references/prompts.md for complete list. Examples:

Library & Downloads:

• "Show me what's downloading right now"
• "What movies were added this week?"
• "Generate a dashboard of my media library"
• "What are the most watched shows this month?"
• "Find all 720p movies that could be upgraded to 4K"
• "Show missing episodes for all monitored shows"
• "What's coming out this week?"
• "Approve all pending Overseerr requests"
• "How much disk space am I using per library?"
• "Show my Plex viewing stats for the last 30 days"
• "What subtitles are missing?"
• "Test all my indexers"

Media Tracking:

• "Set up Trakt tracking for my Plex library"
• "Sync my Plex watch history to Trakt"
• "What am I currently watching on Trakt?"
• "Show my Trakt watch history from this month"
• "Get movie recommendations based on my Trakt ratings"
• "What's trending on Trakt right now?"
• "Export my library for Letterboxd"
• "Compare my Trakt and Simkl watch histories"
• "Show me upcoming movie releases I'm tracking"
• "Rate Inception 10/10 on Trakt"
• "Add Dune Part Two to my Trakt watchlist"
• "Show my Letterboxd profile stats"
• "What are my top-rated movies on Trakt?"

Prowlarr & Indexers:

• "Show all my indexers and test them"
• "Search across all indexers for Breaking Bad"
• "Sync Prowlarr indexers to Sonarr and Radarr"
• "Add Sonarr as a sync target in Prowlarr"

Quality Profiles (Recyclarr):

• "Sync TRaSH Guides quality profiles"
• "Preview what Recyclarr would change"
• "Show available quality profiles for Radarr"
• "What quality definitions does Sonarr have?"

Library Cleanup (Maintainerr):

• "Show my library cleanup rules"
• "What movies are flagged for deletion?"
• "Run all cleanup rules now"
• "Exclude this movie from the cleanup rule"

Collections & Overlays (Kometa):

• "Run Kometa to update collections"
• "Show all my Plex collections"
• "What overlay templates are available?"
• "Add IMDb Top 250 collection to my movie library"

Notifications (Notifiarr):

• "Check Notifiarr status and integrations"
• "Send a test notification"
• "Show recent notifications"

Archive Extraction (Unpackerr):

• "Check Unpackerr status"
• "Show recent extraction activity"
• "Any extraction errors?"

Traktarr/Retraktarr Automation:

• "Set up Traktarr to auto-add trending movies"
• "Add the top 10 anticipated movies from Trakt to Radarr"
• "Configure Traktarr to monitor my Trakt watchlist"
• "Sync my Radarr library to a public Trakt list"
• "Show Traktarr status and configuration"
• "Add trending shows to Sonarr via Traktarr"
• "Set up automatic syncing between Trakt and my *arr apps"
• "What's Retraktarr doing? Is it synced?"

Technical Notes

Bash 3.2 Compatibility

All scripts are compatible with macOS bash 3.2:

• No associative arrays (declare -A)
• No uppercase parameter expansion (${var^^})
• Use $(echo "$var" | tr '[:lower:]' '[:upper:]') for case conversion
• No |& (pipe stderr), use 2>&1 instead

Dependencies

• curl — HTTP requests
• jq — JSON parsing
• bc — Math calculations (for percentages, GB conversions)
• sed — Text processing

All standard on macOS/Linux.

Security

• Never log API keys
• Confirm destructive actions (delete, remove)
• Rate limiting for bulk operations
• Use HTTPS for remote access

Performance

• Scripts cache API responses where possible
• Dashboard generation pulls data once per run
• Bulk operations use batch APIs when available

Version Compatibility

Tested with:

• Sonarr v4.x (API v3)
• Radarr v5.x (API v3)
• Lidarr v2.x (API v1)
• Readarr v0.3.x (API v1)
• Prowlarr v1.x (API v1)
• Bazarr v1.4.x
• Overseerr v1.33.x (API v1)
• Plex Media Server (all recent versions)
• Tautulli v2.x (API v2)
• SABnzbd v4.x
• Recyclarr v7.x
• Unpackerr v0.14.x
• Notifiarr v0.8.x
• Maintainerr v2.x
• Kometa v2.x (Plex Meta Manager successor)
• FlareSolverr v3.x

Contributing

Report issues or suggest features via GitHub. Include:

• Script name and command run
• Error output (sanitize API keys!)
• Service versions
• Platform (Docker/Unraid/Synology/etc)

License

MIT License - See repository for details.