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

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