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.

Prerequisites & Runtime Scope

Required binaries

bash, curl, jq — universally available on macOS/Linux.

Optional binaries

| Binary | When used | |--------|-----------| | bc, sed | Math and text processing in analytics/library scripts | | docker | Companion service management (Kometa, Recyclarr, Unpackerr) — only invoked when RECYCLARR_SSH/KOMETA_SSH/UNPACKERR_SSH env vars are set | | ssh | Remote container access on NAS/Docker hosts — only invoked when *_SSH env vars are set |

If docker and ssh are not installed or no *_SSH env vars are configured, companion-service scripts (kometa.sh, recyclarr.sh, unpackerr.sh) will report unavailable rather than fail silently.

Environment variables

All variables are optional — the skill degrades gracefully when a service key is absent. See the Configuration section for details on each variable.

Core services: CLAWARR_HOST, SONARR_KEY, RADARR_KEY, LIDARR_KEY, READARR_KEY, PROWLARR_KEY, BAZARR_KEY, OVERSEERR_KEY, PLEX_TOKEN, TAUTULLI_KEY, SABNZBD_KEY, NOTIFIARR_KEY

Media trackers (optional): TRAKT_CLIENT_ID, TRAKT_CLIENT_SECRET, SIMKL_CLIENT_ID, SIMKL_CLIENT_SECRET, LETTERBOXD_API_KEY

Companion service SSH (optional): RECYCLARR_SSH, KOMETA_SSH, UNPACKERR_SSH, DOCKER_CONFIG_BASE

Tokens are saved locally to ~/.config/clawarr/ with 600 permissions (user read/write only) and never transmitted to third-party endpoints.

Network access

• Primary: Local LAN / user-configured host IPs (all *arr API calls)
• External (only when corresponding env vars are set):
• api.trakt.tv — Trakt OAuth + watch history sync
• api.simkl.com — Simkl OAuth + history sync
• letterboxd.com — Public profile reads only (no write API used)
• raw.githubusercontent.com — Recyclarr TRaSH-Guides profile downloads (only on recyclarr.sh sync)

Destructive actions

None are triggered automatically. The following require explicit user invocation:

• manage.sh remove — deletes content via Radarr/Sonarr API
• maintainerr.sh run — executes library cleanup rules
• unpackerr.sh restart / kometa.sh run / recyclarr.sh sync — container operations

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 

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 "" [quality] [root]
manage.sh add-series "" [quality] [root]
manage.sh remove  
manage.sh wanted [app]
manage.sh calendar [app] [days]
manage.sh history [app] [count]
manage.sh rename  
manage.sh refresh  [id]

Request Management (requests.sh)

Overseerr request handling:

requests.sh list [pending|approved|available|all]
requests.sh approve 
requests.sh deny  [reason]
requests.sh info 
requests.sh stats

Subtitle Management (subtitles.sh)

Bazarr operations:

subtitles.sh wanted
subtitles.sh history [count]
subtitles.sh search  
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  [type] # Search across all indexers (type: movie|tv|audio|book)
prowlarr.sh apps                  # List sync targets (Sonarr/Radarr/etc)
prowlarr.sh add-app     # 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     # Show media matched by a rule
maintainerr.sh exclude    # 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/

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: omiron33
• Source: omiron33/clawarr-suite
• License: MIT
• Homepage: https://clawhub.com

Install and usage instructions live in the source repository linked above.