PoSH4PlexApp – PowerShell module for managing Plex Media Server

Plex – a quick introduction

As many of you may know, I’m a long time fan of the cross-platform media server, Plex. If you know what Plex is, the feel free to click this link to be taken straight to the PowerShell documentation and code!

As an ex-XBMC user (pun intended), I was initially drawn to Plex’s offering by the fact it looks polished ‘out of the box’ without having to author custom themes. When I discovered it could transcode to iOS devices, I made the leap wholesale, purchasing an Apple Mac Mini front end PC for my home theater downstairs and a Mac Mini Server for my office to run the back-end Media Server.

Of course, since then things have moved on a bit. It’s no longer an Apple-only affair…

Plex now offers native computer clients for Windows Desktop, Windows Modern UI and OSX, with Linux being catered for in the community.

A smorgasbord of mobile platforms are supported with iOS, Android and Windows Phone (horray!) being represented.

Connected device support is pretty much unparalleled with Samsung Smart TVs, Roku &  Amazon Fire TV, GoogleTV and ChromeCast along with generic DNLA  all being supported.

Finally, the Plex dev team have authored servers for computer operating systems (Windows, OSX, Linux & FreeBSD) and plugins for six NAS manufacturers.

But this post isn’t about the clients, or what servers you can run. It’s about…

Managing Plex Media Server

As a long time user of Plex, I have reasonably large library. On occasion, due to hardware failure or hardware upgrade, I’ve had to rebuild said library, and manually flag episode/series/show viewed statuses. More frequently, I’ve had cause to manage my files on the basis of their library metadata (i.e. delete ‘watched’ TV shows) rather than their file data. Batch operations using the mouse are always a pain, so my scripting orientated mind got to thinking…

For a long while now, Plex has supported management of it’s library via a webmin, punching commands over HTTP and supporting returns in the XML format.

For an even longer time, PowerShell has supported invoking HTTP and parsing XML.

Recently, a good buddy of mine, Richard Green, mentioned that Fiddler was a great way of intercepting browser traffic to work out what GET requests web based applications are posting

[See where I’m going here? 😉 ]

So, this weekend I put together a PowerShell script containing functions to enable me to parse and in a limited capacity manage by library. Say welcome to…


PoSH4PlexApp is an in-development PowerShell module for querying and managing PlexApp libraries via Plex Media Server’s web listener. I’ve authored this code with an ethos that wherever possible, I will offload search activities to the Plex Media Server search service , rather than filtering arrays in memory. That said, there were a couple of fringe cases, such as searching for TV shows by ‘viewed’ status, where I had to bake my own, as the API doesn’t surface a method right now.

These functions are currently operational:


Queries the library of the Plex Media Server (PMS) specified for videos, returning metadata attributes. Supports filtering on the basis of ‘viewed’ status, video type (TV, Movies, All), series number, episode number, video name and/or show name


PlexServer : IP address or Hostname of Plex Media Server listening on port 32400
VideoName  : Name of video
VideoType : Type of video  – Can be set to TV, Movie or All
ShowName : Name of TV Show. Will return no results when VideoType set to Movie (obviously)
ViewedStatus : Whether the video has been viewed or not – Can be set to Watched, Unwatched or All
EpisodeNumber : Episode number of video. Cannot be combined with VideoType parameter
SeriesNumber : Series number of video. Cannot be combined with VideoType parameter

Get PlexShow

Queries the TV sections of the PMS library for TV shows, returning metadata attributes. Supports filtering on the basis of show name and/or ‘viewed’ status

PlexServer : IP address or Hostname of Plex Media Server listening on port 32400
ShowName : Name of TV Show
ViewedStatus : Whether the video has been viewed or not – Can be set to Watched, Part-Watched, Unwatched or All


Sets the viewed status (watched/unwatched) of videos, series and shows in the PMS library. Accepts user-typed unique ID (ratingKey) of object from Plex library or pipe-lined input from the above two functions

PlexServer : IP address or Hostname of Plex Media Server listening on port 32400
Key : Unique key of Plex library artefact
ViewedStatus : What you want to set the ‘Viewed’ status to be – Can be set to Watched or Unwatched

I also have the following functions planned for the near future:

Get-PlexSeries – Query library of the PMS for TV series

Set-PlexVideo – Update metadata attributes on Plex video objects

Set-PlexShow – Update metadata attributes on Plex show objects

Set-PlexSeries – Update metadata attributes on Plex series objects

… however, my first priority is to tidy up the commenting and refactor the current ‘Get’ functions to accept pipeline input. That and providing useful help text for each of the functions, something I typically neglect to do if not beaten into it!

The source code is available below and on CodePlex. Do feel free to reach out to me if you have any feedback or ideas, as they would be gratefully received.

I’ll be doing some deep dive posts over the coming week on how I’m searching the library and handling the objects where I cannot get the Plex Media Server search service to do the lifting on my behalf. I may go into how I put the Cmdlets together, if any interest is expressed, but in all honesty the Hey, Scripting Guy blog does a pretty good job of those sort of tutorials 😉

Leave a Reply