Skill: akivasolutions/plex-ctl (version 1.0.0)

# plexctl — Plex Media Server Control > Standalone CLI for controlling Plex Media Server and clients via the Plex API ## When to Use **Trigger phrases:** - "play [title] on Plex" - "search Plex for [query]" - "what's playing on Plex" - "pause/resume Plex" - "show me what's on deck" - "what's new on Plex" - "list Plex clients" - "tell me about [movie/show]" **Use this skill when:** - User wants to play specific content on Plex - User wants to search their Plex library - User wants to control playback (pause, resume, stop, next, prev) - User wants to see what's currently playing - User wants to browse recently added content - User wants to see continue watching (on-deck) - User wants detailed info about a title **Don't use this skill when:** - User wants Apple TV-specific navigation (use ClawTV instead) - User wants vision-based automation (use ClawTV instead) - User wants to manage Plex server settings (use Plex web UI) ## Commands ### Setup ```bash plexctl setup ``` Interactive first-time setup: - Plex server URL (e.g., http://192.168.86.86:32400) - Plex token - Default client selection ### Playback ```bash # Play a movie (fuzzy search) plexctl play "Fight Club" plexctl play "inception" # Play specific TV episode plexctl play "The Office" -s 3 -e 10 plexctl play "Westworld" --season 2 --episode 6 # Play on specific client (overrides default) plexctl play "Matrix" -c "Living Room TV" ``` ### Playback Control ```bash plexctl pause # Pause current playback plexctl resume # Resume playback plexctl stop # Stop playback plexctl next # Skip to next track/episode plexctl prev # Go to previous track/episode ``` ### Search & Discovery ```bash # Search across all libraries plexctl search "matrix" plexctl search "breaking bad" # Recently added content plexctl recent # Last 10 items plexctl recent -n 20 # Last 20 items # Continue watching (on-deck) plexctl on-deck # What's currently playing plexctl now-playing # Detailed info about a title plexctl info "Inception" plexctl info "The Office" ``` ### Library Management ```bash # List all libraries plexctl libraries # List available clients plexctl clients ``` ## Setup Instructions ### 1. Install Dependencies ```bash pip install plexapi ``` ### 2. Run Setup ```bash plexctl setup ``` You'll need: - **Plex server URL**: Usually `http://[local-ip]:32400` - **Plex token**: Get from Settings → Account → Authorized Devices - Or from browser URL when logged into Plex Web - Look for `X-Plex-Token` parameter - **Default client**: The tool will discover available clients ### 3. Verify ```bash plexctl clients # Should list your devices plexctl libraries # Should list your libraries plexctl search "test" # Should return results ``` ## Required Credentials Config stored in `~/.plexctl/config.json`: ```json { "plex_url": "http://192.168.86.86:32400", "plex_token": "your-plex-token-here", "default_client": "Apple TV" } ``` ### Getting Your Plex Token **Method 1: Settings Page** 1. Log into Plex Web (app.plex.tv) 2. Settings → Account → Authorized Devices 3. Look for your token in the page source or URL **Method 2: Browser URL** 1. Open any Plex Web page while logged in 2. Check the URL for `X-Plex-Token=...` 3. Copy the token value **Method 3: XML Direct Method** 1. Navigate to: `http://[your-plex-ip]:32400/?X-Plex-Token=` 2. View page source 3. Look for `authToken` attribute ## Privacy & Data - **Local only**: Connects directly to your Plex Media Server on your local network - **No cloud APIs**: All communication is local (unless using Plex cloud discovery as fallback) - **No external services**: No data sent to third parties - **No telemetry**: No usage tracking or analytics - **Config storage**: Only stores Plex URL, token, and default client locally **Note**: Plex cloud discovery (MyPlex) is only used as a fallback when local GDM discovery fails. All media playback is direct to your local server. ## Common Use Cases ### 1. Quick Movie Playback ```bash plexctl play "Fight Club" ``` Searches library, finds best match, starts playing on default client. ### 2. Binge Watching TV Shows ```bash plexctl play "Breaking Bad" -s 1 -e 1 # ... watch episode ... plexctl next # Next episode plexctl next # Next episode ``` ### 3. Continue Watching ```bash plexctl on-deck # See what's in progress plexctl play "Show Name" # Resume from where you left off ``` ### 4. Browse New Content ```bash plexctl recent # See what's new plexctl info "Movie Title" # Get details plexctl play "Movie Title" # Watch it ``` ### 5. Multi-Client Control ```bash plexctl clients # List all clients plexctl play "Movie" -c "Bedroom TV" # Play on specific client plexctl pause -c "Living Room TV" # Pause specific client ``` ### 6. Library Search ```bash plexctl search "christopher nolan" # Find all Nolan films plexctl search "breaking" # Fuzzy search plexctl info "Inception" # Get details before watching ``` ## Fuzzy Matching The `play` and `info` commands use fuzzy search: - "fight club" → "Fight Club (1999)" - "inception" → "Inception" - "office" → "The Office (U.S.)" Exact matches are prioritized over partial matches. ## Error Handling **Client not found:** ``` Error: Client 'Apple TV' not found Available clients: Local: • Living Room TV (Plex for Apple TV) • Bedroom (Plex Web) ``` **No results:** ``` No results found for: xyz123 ``` **Connection failed:** ``` Error connecting to Plex server: [Errno 61] Connection refused URL: http://192.168.86.86:32400 Check your plex_url and plex_token in config ``` ## Integration with OpenClaw When a user asks to play something on Plex: 1. **Parse the request** — extract title, season, episode 2. **Choose command:** - Movie: `plexctl play "Title"` - TV show specific episode: `plexctl play "Show" -s N -e N` - Search first: `plexctl search "query"` then `plexctl play "Title"` 3. **Execute and report** — run command, share output with user **Example agent flow:** ``` User: "Play Fight Club on Plex" Agent: [exec] plexctl play "Fight Club" Output: Found: Fight Club (1999) (movie) ✓ Playing on Apple TV Agent: "Now playing Fight Club on your Apple TV" ``` ## Troubleshooting **Can't connect to Plex:** - Verify server is running - Check URL (should be http://IP:32400, not https) - Verify token is correct - Check firewall settings **Client not found:** - Make sure Plex app is open on the client device - Run `plexctl clients` to see available clients - Try cloud discovery (automatic fallback) - Restart Plex app on client device **Playback fails:** - Verify client can play the content type - Check client is still active (`plexctl clients`) - Try playing manually in Plex app first - Check Plex server logs **Search returns no results:** - Verify content exists in your library - Try broader search terms - Check library is scanned and up-to-date - Run `plexctl libraries` to verify library access ## Performance - **Local GDM discovery**: ~100ms - **Cloud fallback discovery**: ~500-1000ms - **Search**: ~200-500ms depending on library size - **Playback start**: ~500ms - **Control commands**: ~100ms All operations are direct Plex API calls — no vision, no screenshots, no AI inference needed. ## Differences from ClawTV | Feature | plexctl | ClawTV | |---------|---------|--------| | Plex control | ✅ Direct API | ✅ API + Vision | | Apple TV remote | ❌ | ✅ | | Vision-based navigation | ❌ | ✅ | | Any streaming app | ❌ | ✅ | | Speed | ⚡ Instant | 🐢 Slower (screenshots) | | Dependencies | plexapi only | pyatv, Anthropic API, QuickTime | | Use case | Plex-only control | Universal TV automation | **When to use plexctl**: Fast, direct Plex control **When to use ClawTV**: Complex navigation, non-Plex apps, vision-based automation


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)