plex-query

What this skill does

# Plex Query Skill

## Purpose

This skill enables querying a Plex Media Server to answer natural language questions about available movies and TV shows. Use the provided CLI tools to filter media by duration, genre, ratings, actors, directors, year, and watch status. The tools are optimized for LLM use with JSON output and sensible defaults.

## When to Use This Skill

Use this skill when users ask questions about their Plex library, including:

- Finding movies or shows based on specific criteria (genre, duration, ratings, actors)
- Checking watch status ("what haven't I seen", "shows I've started")
- Time-constrained viewing ("I have 90 minutes, what can I watch")
- Recommendations based on ratings or awards
- Queries about specific shows or actors

## Available Tools

Three Python CLI tools are provided in the skill's `scripts/` directory. All tools use PEP 723 inline script metadata with uv for automatic dependency management, output JSON by default, and accept standard filtering parameters optimized for LLM patterns.

The scripts can be run directly:

```bash
cd scripts/
./plex-movie [options]
./plex-tv [options]
./plex-genres [options]
```

Or with uv explicitly:

```bash
uv run --no-project --script scripts/plex-movie [options]
```

### plex-movie

Search and filter movies in the Plex library.

**Common parameters:**

- `--max-duration MINUTES` - Maximum runtime in minutes (e.g., 120 for 2 hours)
- `--genre GENRE` - Filter by genre with OR logic (fuzzy matching, case-insensitive, can be specified multiple times - at least one must match)
- `--genre-and GENRE` - Filter by genre with AND logic (all specified genres must match, can be repeated)
- `--exclude-genre GENRE` - Exclude genre with NOT logic (none of the specified genres can match, can be repeated)
- `--actor NAME` - Filter by actor name (partial matching)
- `--director NAME` - Filter by director name (partial matching)
- `--year YEAR` - Exact year (e.g., 1995)
- `--decade DECADE` - Decade filter (e.g., "90s", "1990s", "1990")
- `--min-rating RATING` - Minimum rating (0-10 scale, checks all available ratings)
- `--unwatched` - Only show unwatched movies (default behavior)
- `--watched` - Only show watched movies
- `--all` - Show all movies regardless of watch status
- `--limit N` - Maximum results (default: 20)
- `--library NAME` - Specific library to search (uses config default if not specified)

**Output fields:**
Each movie object includes: title, year, duration (minutes), genres (array), rating (best available), actors (array), directors (array), summary, watch status, added date, and more.

**Example usage:**

```bash
# Find romantic movies under 100 minutes
plex-movie --genre romance --max-duration 100

# Tom Cruise movies from the 90s
plex-movie --actor "Tom Cruise" --decade 90s

# High-rated unwatched movies
plex-movie --min-rating 8.0 --unwatched

# Comedy OR action movies (at least one genre must match)
plex-movie --genre comedy --genre action --unwatched

# Movies that are BOTH sci-fi AND thriller
plex-movie --genre-and "sci-fi" --genre-and thriller --min-rating 7.0

# Action movies but NOT horror
plex-movie --genre action --exclude-genre horror

# Complex: (Comedy OR Action) AND British AND NOT Sci-Fi
plex-movie --genre comedy --genre action --genre-and british --exclude-genre scifi
```

### plex-tv

Search and filter TV shows in the Plex library.

**Show-level parameters:**

- `--genre GENRE` - Filter by genre with OR logic (fuzzy matching, can be specified multiple times - at least one must match)
- `--genre-and GENRE` - Filter by genre with AND logic (all specified genres must match, can be repeated)
- `--exclude-genre GENRE` - Exclude genre with NOT logic (none of the specified genres can match, can be repeated)
- `--actor NAME` - Filter by actor
- `--year YEAR` - Show release year
- `--decade DECADE` - Decade filter
- `--min-rating RATING` - Minimum rating (0-10 scale)
- `--max-episode-duration MINUTES` - Maximum typical episode length
- `--unwatched-only` - Only shows with 0 episodes watched
- `--started` - Only shows with >0 episodes watched AND unwatched episodes remaining
- `--in-progress` - Alias for --started
- `--completed` - Only fully watched shows
- `--all` - All shows regardless of watch status
- `--limit N` - Maximum results (default: 20)
- `--library NAME` - Specific library to search

**Show-specific queries:**

- `--show-title TITLE` - Get details about a specific show (partial matching)
- `--unwatched-episodes` - When used with --show-title, returns count and list of unwatched episodes

**Output fields:**
Each show object includes: title, year, genres (array), rating, actors (array), episode count (total, watched, unwatched), typical episode duration, seasons, summary, watch progress percentage, and more.

**Example usage:**

```bash
# British comedy shows not yet started
plex-tv --genre comedy --genre-and british --unwatched-only

# Shows with short episodes that user has started
plex-tv --max-episode-duration 30 --started

# Unwatched episodes of a specific show
plex-tv --show-title "Always Sunny" --unwatched-episodes

# All sci-fi shows from the 2010s
plex-tv --genre "sci-fi" --decade 2010s --all

# Comedy OR Drama shows (at least one must match)
plex-tv --genre comedy --genre drama --unwatched-only

# Shows that are BOTH crime AND drama
plex-tv --genre-and crime --genre-and drama --min-rating 8.0

# Any genre except reality TV
plex-tv --exclude-genre reality --exclude-genre "reality-tv"

# Complex: (Comedy OR Action) AND British AND NOT Sci-Fi
plex-tv --genre comedy --genre action --genre-and british --exclude-genre scifi
```

### plex-genres

List all available genres in the Plex library.

**Parameters:**

- `--type movies` - List movie genres (default)
- `--type tv` - List TV show genres
- `--type all` - List all genres

**Output:**
JSON array of genre names found in the library.

**Example usage:**

```bash
# List movie genres
plex-genres

# List TV genres
plex-genres --type tv
```

Use this tool when the user's genre query doesn't match exactly, or to discover available genres for better filtering.

## Workflow for Answering Queries

### Step 1: Parse User Intent

Identify the key filtering criteria from the user's question:

- Media type (movie vs TV show)
- Duration constraints ("I have 100 minutes")
- Genre preferences ("romantic", "comedy", "sci-fi")
- People (actors, directors)
- Time period (year, decade)
- Watch status ("haven't seen", "already started", "unwatched episodes")
- Rating requirements ("highly rated", "90%+", "award-winning")

### Step 2: Select the Appropriate Tool

- Use `plex-movie` for movie queries
- Use `plex-tv` for TV show queries
- Use `plex-genres` if genre matching might be ambiguous

### Step 3: Construct the Command

Map user criteria to CLI parameters. Common mappings:

- "I have X minutes" → `--max-duration X` (for movies) or `--max-episode-duration X` (for TV)
- "romantic" → `--genre romance`
- "Tom Cruise" → `--actor "Tom Cruise"`
- "from the 90s" → `--decade 90s`
- "haven't seen" → `--unwatched` (movies) or `--unwatched-only` (TV)
- "already started" → `--started` (TV shows)
- "highly rated" → `--min-rating 8.0`

### Step 4: Execute and Parse Results

Run the CLI tool using the Bash tool. The output will be JSON with comprehensive metadata.

### Step 5: Present Results

Format the results for the user:

- Summarize the count ("I found 5 movies matching your criteria")
- List recommendations with relevant details (title, year, duration, rating, brief summary)
- Highlight why each recommendation matches the criteria
- Note watch status if relevant

## Handling Edge Cases

### No Results Found

If the query returns no results:

1. Try relaxing constraints (e.g., increase duration limit, remove genre filter)
2. Use `plex-genres` to verify genre spelling
3. Suggest alternative criteria to the user

### Ambiguous Genres

If a genre term might not match exactly:

1. First try the query with the user's term
2. If