plex

name	plex
description	This skill should be used when the user wants to interact with their Plex Media Server. Triggers include: "check Plex", "search Plex", "what's on Plex", "what's playing on Plex", "who's watching", "Plex sessions", "active streams", "Plex library", "browse movies", "browse TV shows", "recently added", "on deck", "continue watching", "Plex status", or any mention of Plex Media Server.

Plex Media Server Skill

Control and query Plex Media Server using the Plex API. Browse libraries, search media, and monitor active sessions.

Purpose

This skill provides read-only access to your Plex Media Server:

• Browse library sections (Movies, TV, Music, Photos)
• Search for specific media
• View recently added content
• Check what's currently playing (active sessions)
• View "On Deck" (continue watching)
• List available clients/players

All operations are GET-only and safe for monitoring/browsing.

Setup

Credentials are configured in the arrs plugin settings (userConfig). A SessionStart hook writes them to ~/.config/lab-arrs/config.env, which the scripts load automatically — no manual file editing. Variables used:

# Plex Media Server
PLEX_URL="http://192.168.1.100:32400"
PLEX_TOKEN="<your_plex_token>"

• PLEX_URL: Your Plex server URL with port (default: 32400)
• PLEX_TOKEN: Your Plex authentication token

Getting your Plex token:

1. Go to plex.tv → Account → Authorized Devices
2. Click on any device, then "View XML"
3. Find X-Plex-Token in the URL
4. Or: Open any media in Plex Web, click "Get Info" → "View XML" and find token in URL

Commands

All commands output JSON. Use jq for formatting or filtering.

The plex-api.sh helper script simplifies API access. Located at: scripts/plex-api.sh

Server Info

# Using helper script
./scripts/plex-api.sh info

# Or raw curl
curl -s "$PLEX_URL/" -H "X-Plex-Token: $PLEX_TOKEN" -H "Accept: application/json"

Browse Libraries

List all library sections:

# Using helper script
./scripts/plex-api.sh libraries

# Or raw curl
curl -s "$PLEX_URL/library/sections" -H "X-Plex-Token: $PLEX_TOKEN" -H "Accept: application/json"

List Library Contents

# Using helper script (replace 1 with your section key)
./scripts/plex-api.sh library 1
./scripts/plex-api.sh library 1 --limit 50 --offset 100

# Or raw curl
curl -s "$PLEX_URL/library/sections/1/all" -H "X-Plex-Token: $PLEX_TOKEN" -H "Accept: application/json"

Search Media

# Using helper script
./scripts/plex-api.sh search "Inception"
./scripts/plex-api.sh search "Avengers" --limit 10

# Or raw curl
curl -s "$PLEX_URL/search?query=SEARCH_TERM" -H "X-Plex-Token: $PLEX_TOKEN" -H "Accept: application/json"

Recently Added

# Using helper script (default: 20 items)
./scripts/plex-api.sh recent
./scripts/plex-api.sh recent --limit 10

# Or raw curl
curl -s "$PLEX_URL/library/recentlyAdded" -H "X-Plex-Token: $PLEX_TOKEN" -H "Accept: application/json"

On Deck (Continue Watching)

# Using helper script (default: 10 items)
./scripts/plex-api.sh ondeck
./scripts/plex-api.sh ondeck --limit 5

# Or raw curl
curl -s "$PLEX_URL/library/onDeck" -H "X-Plex-Token: $PLEX_TOKEN" -H "Accept: application/json"

Active Sessions (What's Playing)

# Using helper script
./scripts/plex-api.sh sessions

# Or raw curl
curl -s "$PLEX_URL/status/sessions" -H "X-Plex-Token: $PLEX_TOKEN" -H "Accept: application/json"

List Clients/Players

# Using helper script
./scripts/plex-api.sh clients

# Or raw curl
curl -s "$PLEX_URL/clients" -H "X-Plex-Token: $PLEX_TOKEN" -H "Accept: application/json"

Additional Commands

# Server identity
./scripts/plex-api.sh identity

# Get metadata for specific item (by rating key)
./scripts/plex-api.sh metadata 12345

# Get children of item (e.g., seasons of a TV show)
./scripts/plex-api.sh children 12345

# List playlists
./scripts/plex-api.sh playlists

# Refresh library section (scan for new media)
./scripts/plex-api.sh refresh 1

# View all commands
./scripts/plex-api.sh --help

Workflow

When the user asks about Plex:

1. "What's on Plex?" → Browse libraries and show section overview
2. "Search for Inception" → Run search with query
3. "What was recently added?" → Run recentlyAdded
4. "Who's watching right now?" → Run sessions
5. "What am I watching?" → Run onDeck
6. "List my movies" → List library sections, then contents of Movies section

Library Section Types

Common section types (keys vary by server):

• Movies — Usually section 1
• TV Shows — Usually section 2
• Music — Music library
• Photos — Photo library

Always list sections first to get the correct section keys for your server.

Output Format

• Add -H "Accept: application/json" for JSON output
• Default output is XML if header not specified
• Media keys look like /library/metadata/12345
• Use jq to filter and format JSON responses

Notes

• Requires network access to your Plex server
• All calls are read-only GET requests
• Library section keys (1, 2, 3...) vary by server setup — list sections first
• Playback control is possible but not implemented (safety)
• Always confirm before triggering playback on remote devices
• Token is scoped to your account — keep it secure

Multiple Servers

To query multiple Plex servers:

# Server 1
PLEX_URL="http://server1:32400" PLEX_TOKEN="token1" curl ...

# Server 2
PLEX_URL="http://server2:32400" PLEX_TOKEN="token2" curl ...

Reference

• Plex Media Server API
• Plex Web App

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

---