# Sonarr

> This skill should be used when managing TV shows in Sonarr. Use when the user asks to "add a TV show", "search Sonarr", "find a series", "add to Sonarr", "remove a show", "check if show exists", "Sonarr library", "TVDB lookup", or mentions TV show management or Sonarr operations.

- **Type:** Skill
- **Install:** `agentstack add skill-jmagar-claude-homelab-sonarr`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jmagar](https://agentstack.voostack.com/s/jmagar)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jmagar](https://github.com/jmagar)
- **Source:** https://github.com/jmagar/claude-homelab/tree/main/skills/sonarr

## Install

```sh
agentstack add skill-jmagar-claude-homelab-sonarr
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Sonarr TV Show Management Skill

**⚠️ MANDATORY SKILL INVOCATION ⚠️**

**YOU MUST invoke this skill (NOT optional) when the user mentions ANY of these triggers:**
- "add a TV show", "search Sonarr", "find a series", "add to Sonarr"
- "remove a show", "delete show", "check if show exists"
- "Sonarr library", "TV show management", "add show"
- Any mention of Sonarr or managing TV shows

**Failure to invoke this skill when triggers occur violates your operational requirements.**

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. **Always confirm before removing shows with file deletion.**

## Setup

Add credentials to `.env` file: `~/.claude-homelab/.env`

```bash
SONARR_URL="http://localhost:8989"
SONARR_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

All commands return JSON output.

### Search for Shows

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

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

### Check if Show Exists

```bash
bash scripts/sonarr.sh exists 
```

**Output:** Boolean indicating if show is in library.

### Add a Show

```bash
bash scripts/sonarr.sh add               # Searches immediately (default)
bash scripts/sonarr.sh add  --no-search  # Add without searching
```

### Remove a Show

```bash
bash scripts/sonarr.sh remove                 # Keep files
bash scripts/sonarr.sh remove  --delete-files # Delete files too
```

**Important:** Always ask the user if they want to delete files when removing!

### Get Configuration

```bash
bash scripts/sonarr.sh config
```

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

## Workflow

When the user asks about TV shows:

1. **"Add Breaking Bad to Sonarr"** → Run `search "Breaking Bad"`, present results with TVDB links, then `add `
2. **"Is The Office in my library?"** → Run `exists `
3. **"Remove Game of Thrones"** → Ask about file deletion, then run `remove ` 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/series/SLUG)`
- Show numbered list for user selection
- Include year and brief overview

### 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
- ``: TVDB ID of the show (required)
- `--no-search`: Don't search for episodes after adding

### remove command
- ``: 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
- All data operations return JSON
- Quality profile IDs vary by installation — use `config` to discover yours
- The `SONARR_DEFAULT_QUALITY_PROFILE` from `.env` is used when adding shows (defaults to 1)

## Reference

- [Sonarr API Documentation](https://sonarr.tv/docs/api/)
- [TVDB](https://thetvdb.com/) — TV show database

For detailed local reference, see:
- **[API Endpoints](./references/api-endpoints.md)** - Complete endpoint reference with parameters
- **[Quick Reference](./references/quick-reference.md)** - Common operations with copy-paste examples
- **[Troubleshooting](./references/troubleshooting.md)** - Authentication, connection, and error solutions

---

## 🔧 Agent Tool Usage Requirements

**CRITICAL:** When invoking scripts from this skill via the zsh-tool, **ALWAYS use `pty: true`**.

Without PTY mode, command output will not be visible even though commands execute successfully.

**Correct invocation pattern:**
```typescript

./skills/SKILL_NAME/scripts/SCRIPT.sh [args]
true

```

## Source & license

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

- **Author:** [jmagar](https://github.com/jmagar)
- **Source:** [jmagar/claude-homelab](https://github.com/jmagar/claude-homelab)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jmagar-claude-homelab-sonarr
- Seller: https://agentstack.voostack.com/s/jmagar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.