sonarr

name	sonarr
description	This skill should be used when the user wants to manage TV shows in Sonarr. Triggers include: "add a TV show", "add to Sonarr", "search Sonarr", "find a series", "remove a show", "delete show", "check if show exists", "is [show] in my library", "what's airing this week", "upcoming episodes", "Sonarr library", or any general mention of Sonarr or TV show library management.

Sonarr TV Show Management Skill

Search and add TV shows to your Sonarr library with support for monitor options, quality profiles, and search-on-add.

Purpose

This skill enables management of your Sonarr TV show library:

• Search for TV shows by name
• Add shows to your library with configurable options
• Check if shows already exist
• Remove shows (with optional file deletion)
• View quality profiles and root folders

Operations include both read and write actions.

Safety

remove <tvdbId> --delete-files permanently deletes the show's downloaded files from disk with no undo. Always confirm the exact show and whether the user wants files deleted before running it — the script has no confirmation prompt of its own.

Setup

Credentials are configured in the plugin settings (userConfig). The plugin setup script writes them to ~/.config/lab-sonarr/config.json, which the scripts parse automatically — no manual file editing. Variables used:

SONARR_URL="http://localhost:8989"
SONARR_API_KEY="<your_api_key>"
SONARR_DEFAULT_QUALITY_PROFILE="1"  # Optional: defaults to 1 if not set

Configuration variables:

• SONARR_URL: Your Sonarr server URL (no trailing slash)
• SONARR_API_KEY: API key from Sonarr (Settings → General → API Key)
• SONARR_DEFAULT_QUALITY_PROFILE: Quality profile ID (optional, defaults to 1)

Commands

The search-json command returns raw JSON; all other commands return formatted text.

Search for Shows

./scripts/sonarr.sh search "Breaking Bad"
./scripts/sonarr.sh search "The Office"

Output: Numbered list with TVDB IDs, titles, years, and TVDB links.

Search for Shows (raw JSON)

./scripts/sonarr.sh search-json "Breaking Bad"
./scripts/sonarr.sh search-json "The Office"

Output: Raw JSON search results (includes overview and additional metadata).

Check if Show Exists

./scripts/sonarr.sh exists <tvdbId>

Output: Boolean indicating if show is in library.

Add a Show

./scripts/sonarr.sh add <tvdbId>                          # Searches immediately (default)
./scripts/sonarr.sh add <tvdbId> [profileId]              # Use a specific quality profile
./scripts/sonarr.sh add <tvdbId> [profileId] --no-search  # Add without searching

Limitation: add always uses the first root folder returned by Sonarr's API, with no override — on a multi-root-folder instance (e.g. separate anime/TV folders) this can silently place a show in the wrong location. If root folder placement matters, verify with config first and warn the user this can't be overridden via the script.

Remove a Show

./scripts/sonarr.sh remove <tvdbId>                # Keep files
./scripts/sonarr.sh remove <tvdbId> --delete-files # Delete files too

See ## Safety above — confirm file deletion with the user before running this with --delete-files.

Get Configuration

./scripts/sonarr.sh config

Output: Available root folders and quality profiles with their IDs.

Upcoming Episodes / Calendar

./scripts/sonarr.sh calendar        # Next 7 days
./scripts/sonarr.sh calendar 14     # Next 14 days

Output: Air date, show, season/episode, and episode title for each upcoming episode in the window, sorted chronologically.

Workflow

When the user asks about TV shows:

1. "Add Breaking Bad to Sonarr" → Run search "Breaking Bad", present results with TVDB IDs and links, run exists <tvdbId>, then add <tvdbId> if absent
2. "Is The Office in my library?" → Run search "The Office" to identify the TVDB ID, then exists <tvdbId>
3. "Remove Game of Thrones" → Ask about file deletion, then run remove <tvdbId> with appropriate flag
4. "What quality profiles do I have?" → Run config

Presenting Search Results

Always include TVDB links when presenting search results:

• Format: [Title (Year)](https://thetvdb.com/dereferrer/series/TVDB_ID)
• Show numbered list for user selection
• Include year, TVDB ID, and a brief overview when using search-json

Adding Shows

1. Search for the show
2. Present results with TVDB links
3. User picks a number
4. Add show (searches for episodes by default)

Parameters

add command

• <tvdbId>: TVDB ID of the show (required)
• profileId: Optional quality profile ID (defaults to first available profile)
• --no-search: Don't search for episodes after adding

remove command

• <tvdbId>: TVDB ID of the show (required)
• --delete-files: Also delete media files (default: keep files)

Notes

• Requires network access to your Sonarr server
• Uses Sonarr API v3
• Quality profile IDs vary by installation — use config to discover yours
• The SONARR_DEFAULT_QUALITY_PROFILE from plugin settings (config.json) is used when adding shows (defaults to 1)
• scripts/sonarr.sh implements the commands above and nothing more. The references/ docs below additionally cover a much larger raw-API surface (queue, episode monitoring, manual release search/download, RSS sync, history) via direct curl calls — those aren't wired into the script and should be treated as advanced/unverified starting points, not a guaranteed extension of the wrapper's behavior.

Reference

• Sonarr API Documentation
• TVDB — TV show database

For detailed local reference, see:

• API Endpoints - Complete endpoint reference with parameters
• Quick Reference - Common operations with copy-paste examples
• Troubleshooting - Authentication, connection, and error solutions

---