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]"

• 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

• 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

plexctl setup

• Plex server URL (e.g., http://192.168.86.86:32400)
• Plex token
• Default client selection

Playback

# 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

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

# 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

# List all libraries
plexctl libraries

# List available clients
plexctl clients

Setup Instructions

1. Install Dependencies

pip install plexapi

2. Run Setup

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

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:

{
  "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

• Log into Plex Web (app.plex.tv)
• Settings → Account → Authorized Devices
• Look for your token in the page source or URL

• Open any Plex Web page while logged in
• Check the URL for X-Plex-Token=...
• Copy the token value

• Navigate to: http://[your-plex-ip]:32400/?X-Plex-Token=
• View page source
• 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

Common Use Cases

1. Quick Movie Playback

plexctl play "Fight Club"

2. Binge Watching TV Shows

plexctl play "Breaking Bad" -s 1 -e 1
# ... watch episode ...
plexctl next                    # Next episode
plexctl next                    # Next episode

3. Continue Watching

plexctl on-deck                 # See what's in progress
plexctl play "Show Name"        # Resume from where you left off

4. Browse New Content

plexctl recent                  # See what's new
plexctl info "Movie Title"      # Get details
plexctl play "Movie Title"      # Watch it

5. Multi-Client Control

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

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.)"

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:

• Parse the request — extract title, season, episode
• 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"
• Execute and report — run command, share output with user

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

• 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

• 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

• 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

Differences from ClawTV