- Created by BenjaminOddou
- ๐ Last Updated: 21/11/26 19:02:49
- ๐ Stars on GitHub: 26
- Please consider supporting the creator by Starring or Sponsoring them on GitHub!
- Get Latest Release
- Get Source Code
From their README
โจ Welcome to the Alfred Plex repository: An Alfred Workflow โจ

โ Prerequisites
- macOS.
- Alfred 6 with the Alfred Powerpack. Alfred 5.5 still runs the workflow (Grid View and Text View), without the Alfred 6 extras.
- An access to a plex media server.
- Python 3.10 or above (required by python-plexapi 4.18). The Python shipped with the Xcode command line tools
is 3.9: install a recent one with Homebrew (
brew install python) or from python.org. The workflow looks forpython3in/opt/homebrew/bin,/usr/local/binthen in the systemPATH, and tells you when the version is too old.
python3 --version
โฌ๏ธ Installation
- Download the workflow.
- Double click the
.alfredworkflowfile to install.
Upgrading from 2.x keeps your accounts, servers, presets and aliases (2.x removed them at every update).
๐ Alfred 6
The workflow uses what Alfred 6 brings to workflows:
- Native notifications: Alfred posts them itself (Post Notification output, macOS UserNotifications). The
Notificator helper app is gone, the old copy is removed from the cache at the first run. They can be turned off
with
๐ Notifications, as in Alfred Emoji Wine. - Strict modifier keys (
strictmods): a modifier a row doesn't use (โฅโ on a menu row, a disabled shortcut on a media...) does nothing, instead of running the โ action by surprise. - Posters keep their shape (
iconresize): in the List with posters view, the 2:3 posters fit in the icon instead of being stretched to a square.
๐๏ธ Plex API
This workflow uses Python-PlexAPI 4.18.3 and doesn't cover all capabilities of this tool. If you see a good feature from the Python-PlexAPI that can be incorporated in this workflow, please let me know by opening an issue or sending a pull request.
๐งโโ๏ธ Invoke the workflow
Launch the menu with plex (the keyword can be changed in the
Workflow Configuration panel). New here? The menu shows Sign in with Plex and Getting started: one press on โ and your servers
are added.
The workflow is divided in 6 parts:
- ๐ Plex Search: type to search your servers; empty, it lists your libraries to browse them as a list or as posters, sorted and filtered by picking. โ on a media opens all its actions.
- ๐งญ Plex Discover: search movies, shows and people on Plex Discover (also as posters).
- ๐ฅ Plex Accounts: sign in with Plex, users, devices (clean up old ones), watchlist.
- ๐ฅ๏ธ Plex Media Servers: sessions, recently added, continue watching, libraries, statistics, settings, maintenance, activities.
- ๐๏ธ Plex Presets: saved searches (save one from the last row of Plex Search).
- ๐ Plex Help: getting started, shortcuts, filters & sorts, alias, cache, logs export.
The menu subtitles show what is configured (servers, accounts, presets).

If you're not the owner of a server, you only see its medias (no management).
๐งญ Navigation
- Every screen has a Return row, prompts included, and Return goes back to the screen you came from (a real history: server โ account โ Return brings you back to the server, with your search query when you came from a search). Its subtitle tells where you go. In live searches it's the last row, so โ still opens the first result.
- โโ on Return jumps straight back to the main menu.
- Alfred stays open: while an action runs (rating, played state, sync, export...), a โณ loading page
shows what is happening, then the page you were on comes back with a โ
/ ๐จ banner. Long actions (exports,
downloads, sign in) and errors also end with one macOS notification posted by Alfred (with the
๐ท Notification sound), you can close Alfred meanwhile. Untick๐ Notificationsto keep the workflow silent: no notification, no sound (the loading page and the logs still tell what happened). - Full details open on top of the current page: โ (or โฉ) brings you back to it.
- Pages are filtered by Alfred while you type (type
setin a server page to only seeSettings). - After an action (watchlist, preset, alias...) you come back to the page you were on, with your search query, instead of an empty search.
- Destructive actions (remove an account, a device, clear a folder...) show a Yes / Cancel page instead of
asking you to type
yes.
๐ค Usage of the workflow
๐ Libraries (Plex Search, empty): posters, sort and filters without syntax
Open Plex Search without typing: your library sections are listed first (โ list, โโ posters). Everything is chosen in lists, nothing to type:
- โ๏ธ Sort: every sort of the section (date added, release date, title, rating, duration, last viewed...): โ natural direction, โโ the other one. The current one has a โ.
- โ Filter: genre, year, decade, resolution, collection, actor, studio, content rating... (choose a value), or on / off filters such as Unplayed, In progress, HDR (one โ). Each active filter has a โ row to remove it, Clear all filters removes them all.
- ๐ผ๏ธ Posters: the same selection in Alfred's Grid View. The footer of the selected poster shows year, duration, rating, content rating, resolution and โ played; type to filter the posters by title.
- ๐ Open in Plex Search / ๐พ Save as a preset: the selection becomes a regular filter query.
In the Grid View, a poster does exactly what its row does in the list: same keys, same shortcuts (โ, โโ,
โฅโ, โโ, โงโ, fnโ, โโงโ as configured), the โ action, โง / โY Quick Look. A nested search (seasons of a show,
tracks of an album, medias of an actor...) opens as posters too. Every grid also has the rows of its list:
๐ Edit the search, ๐พ Save as a preset, โฐ List view, sort and filters for a library. Type in the grid to
filter the posters (title, year, type, server, genres). Posters are available for Plex Search results, Plex
Discover results, your watchlist, recently added, continue watching and the content of any show / collection
(๐ผ๏ธ Show as posters rows). The number of columns is the ๐ผ๏ธ Poster columns setting.
Posters are resized by your server (300ร450) and cached: they are downloaded once, then also used as icons in the list views.
๐ผ๏ธ Results view: list, list with posters or grid
Choose how Plex Search and Plex Discover show their results with the ๐ Results view setting
(Workflow Configuration):
| Setting | What you get |
|---|---|
| โฐ List (no images) (default) | the classic list with type icons: the fastest. |
| ๐ผ๏ธ List with posters | the same list, each row shows the poster (Plex Search, Plex Discover, libraries, recently added, continue watching, watchlist). |
| โฆ Grid (posters) | you search exactly like in the list (live results with posters while you type), the first row ๐ผ๏ธ Show as posters (โ) shows them in Alfred's Grid View, with the same shortcuts. Empty Plex Search: โ on a library opens its posters (โโ as a list). |
Alfred's Grid View can't run a search on each keystroke (its script runs once, typing only filters the posters already shown). So the search is typed in Plex Search / Plex Discover, and ๐ Edit the search in the grid brings you back to it with your query.
๐งน Poster cache
Posters are kept in Alfred's cache folder (~/Library/Caches/com.runningwithcrayons.Alfred/Workflow Data/com.benjamino.plex/posters), with the user avatars. Plex Help โบ Workflow Cache & Logs โบ ๐ผ๏ธ Posters &
avatars lists them (type to find one) with their size:
- ๐งน Purge all posters removes them all (with a confirmation).
- โ on a poster removes only this one, โโ shows it in Finder.
- The media actions page also has ๐งน Remove the cached poster.
A removed poster is downloaded again the next time it is shown.
โก๏ธ Right arrow: an action of your choice
Press โ on a media (Plex Search, Plex Discover, libraries, recently added, posters...): Alfred shows its
actions panel for the media title (The Matrix (1999) ยท Home Server). Type plex (or pick Plex, Alfred puts it
first once you used it) and โฉ: the action chosen in the โก๏ธ Right arrow setting runs:
| Setting | Action |
|---|---|
| ๐ Full details (default) | the media sheet (Text View): poster, summary, ratings, cast, crew, files. โ or โฉ goes back to your results. |
| ๐ More details | the same as a list: summary, cast (โ their medias), crew, files, ids... Return goes back. |
| โ๏ธ Media actions page | play, mark played, rate, playlists, collections, download... |
| โถ๏ธ Play | streams with your media player (Plex Discover: More details). |
| ๐ Open in Plex Web | app.plex.tv. |
Alfred always opens its actions panel on โ (Universal Actions): a workflow can't skip it, hence the โฉ on Plex. The other actions of the panel (Copy, Large Type...) use the title. โ closes the panel. Plex on any other text in Alfred searches it in Plex Search. The media actions page also has a ๐ More details row.
๐ Full details sheet
From the media actions page (๐ Full details) or โฅโ on a poster, Alfred's Text View shows a Markdown sheet: poster, tagline, release date, duration, content rating, studio, ratings with their source (Rotten Tomatoes, IMDb, TMDB), your rating, played state, summary, cast with characters, directors / writers / producers, genres, countries, collections, labels, edition, library, TMDB / IMDb / TVDB ids and every file with its video, audio and subtitle streams.
Plex Search: search medias throughout your servers
Servers are searched in parallel, so adding servers doesn't make the search slower.
1. Simple search
Type your request. You can optionally add a / followed by one of the following media types: track, album,
artist, collection, actor, director, genre, movie, photo, photoalbum, playlist, show, episode, clip.
Titles containing a / (AC/DC) are searched as is.
Link to the Python-PlexAPI documentation.

2. Advanced search
Search your library sections with filters and/or advanced filters separated by /. A / only starts a
new filter when it's followed by name=, so values may contain /. Only the sections that can answer the
libtype are queried.
Link to the Python-PlexAPI documentation.
The following example libtype=movie/decade=1980/country=france returns movies released between 1980 and
1990 in the country France.

Workflow specific filters:
| Filter | Alias | Example | Description |
|---|---|---|---|
server |
sv |
sv=home,nas |
only search these servers |
section |
sc |
sc=movies |
only search these library sections |
watchlist |
wa |
wa=1 |
only medias on (1) / not on (0) your watchlist |
When the search is empty, the ๐ Default view of the configuration is displayed (python dict or JSON, for
example {"sort": "addedAt:desc"}).
The last row, ๐พ Save this search as a preset, keeps the current query in Plex Presets.
3. Actions on medias
Every shortcut can be changed (or disabled) in the user configuration panel. Plex Help โบ Keyboard Shortcuts lists your current ones.
| Default | Action | Medias |
|---|---|---|
| โ | Nested search, otherwise the media actions page | all |
| fnโ | Media actions page | all but actors / genres |
| โโ | Open on app.plex.tv | all but genres / photos |
| โฅโ | Stream with VLC / IINA / INFUSE | movie, episode, clip, track, album |
| โโ | Movie and TV Show Search | movie, show |
| โงโ | Add / remove watchlist | movie, show |
| โโงโ | Mark played / unplayed (โ shown in the subtitle) | movie, show, season, episode, clip |
| disabled | Download the file(s) | movie, episode, clip, track, album, season |
The media actions page gathers everything in one place: play, browse children (seasons, episodes, tracks...), go to the show / season / album, open on the web, mark played / unplayed, โญ rate (0-10), watchlist, Movie and TV Show Search, โ playlists and ๐๏ธ collections (the ones the media is in come first, โ removes it from them, then the others, โ adds it, or create a new one), ๐ file(s) details (size, container, resolution, codecs, bitrate; โ shows the file in Finder when it's on this Mac or copies its path, โโ copies the direct stream link), โฌ๏ธ download, ๐ refresh metadata, ๐ analyze, โน๏ธ infos (โL for the summary) and ๐๏ธ delete from the server (needs Allow media deletion in the server settings). Return brings you back to your search results.
Details:
- Nested search: on actor, director, collection, artist, album, genre, show, season.
- Open on the web (โโ): open the media on app.plex.tv. Not available for genre.
- Stream (โฅโ) with VLC / IINA / INFUSE: movie, episode, clip, track*, album*. If you have multiple versions of a movie, episode, clip, you choose the file to play (video, audio, subtitles and size are displayed). *INFUSE doesn't accept standalone audio streams.
- Media infos (โโ) with the Movie and TV Show Search workflow by Tom McKnight (2.16.0 or above): movie, show.
- Watchlist (โงโ): add or remove a movie or show from your plex watchlist.
- Poster preview: press โง (tap) or โY to Quick Look the poster.
- Copy: โC copies the title.
4. VLC, IINA and INFUSE integration
If you don't have VLC / IINA on your mac, install it with homebrew:
brew install --cask vlc
brew install --cask iina
The workflow uses their command line tools (vlc / iina), found in /opt/homebrew/bin or /usr/local/bin.
Check them with:
which vlc
which iina
If they are not found, reinstall the application with homebrew. INFUSE doesn't need a command line tool, install the application from the App Store.
Links: VLC homebrew formulae, IINA homebrew formulae, INFUSE website.
Plex Discover: search medias using discover
Search movies, shows and people on Plex Discover (add /movie,
/show or /people to filter). You can perform the same actions listed above, except
streaming. The nested search looks for the media on your servers, and Return brings you back to your
Discover results. With an empty query, the most watchlisted medias are displayed, with ๐ผ๏ธ Show as posters
on top. In the Discover Grid View, the shortcuts are the same as in the list (โ find it on your servers,
โโ web, โโ infos, โงโ watchlist).

Plex Accounts: manage your plex accounts
Connect one or more accounts with Sign in with Plex: your browser opens app.plex.tv, sign in the way you
like (password, 2FA, Google, Apple...). Nothing is typed in Alfred. You have 3 minutes to complete the sign in.
The servers of the account are added automatically (connections are tested in parallel) and a notification tells
you when it's done (the added servers, and the ones that could not be reached).
Since 3.0, sign in is OAuth only: the username / password and token methods are gone.
In this section you can:
- Sync the account (refresh its data and reconnect its servers).
- See the list of your servers. Servers that aren't added to the workflow are greyed out: press โ to sync them.
- See your friends and connected users with their avatar (and export them to CSV). Avatars are also shown on your connected accounts and on the server sessions. They stay in the Alfred cache with the posters (no download to your folders).
- Manage devices, sorted by last activity (
Last seen 3 days ago):- Clean up old devices: removes in one go the devices not seen for 90+ days (
๐งน Old devicessetting). Servers and this workflow are never removed. - โ details (product, version, activity, IP location, Google Maps), โโ remove.
- Export to CSV.
- Clean up old devices: removes in one go the devices not seen for 90+ days (
- Manage your watchlist: โ finds the media on your servers, โโ removes it, export to CSV.

Removing a plex account removes all its servers. You can also remove a server in the Plex Media Servers section.
When connected, the workflow appears in the Authorized Devices section of plex
(documentation). Removing this device from the
workflow also disconnects the account.

Plex Media Servers: manage servers and perform actions
Select a server:
- Update: download the last version, or โโ to let a Mac / Windows server install it.
- Sessions (refreshed every 5 seconds): user, player, progress, Direct Play / Transcode, bandwidth, LAN / WAN. โ media actions, โโ terminate with a message, โฅโ device details, Terminate all when several streams play, export to CSV.
- Recently Added and Continue Watching: media rows with all the shortcuts above.
- Library Sections: scan, refresh, analyze, empty trash, history, recently added, Search in this section, size and duration, export the whole section to CSV (title, year, file path, size, resolution, codecs, views, ratings, TMDB / IMDB ids...).
- Statistics:
- Live: bandwidth, CPU and RAM (with bars), refreshed every second.
- Libraries: items, size and duration per section, share of the storage.
- Plays: plays per day, busiest day, peak hour, top users, titles, libraries, devices and platforms.
- Bandwidth: local / remote traffic, per user, per device and per day.
- Media Quality: 4K / 1080p / 720p / SD / HDR per section.
- Every statistic can be exported to CSV.
- Settings: display, modify and export to CSV. Values are typed naturally:
true/false(oryes/no,1/0) for booleans, numbers forint/doubleand plain text fortext(quotes are optional). - Maintenance: download logs, download databases, empty trash, clean bundles, optimize database, run any scheduled task (backup, cleanups...).
- Activities: what the server is doing right now (scans, analysis...) with progress bars.

๐ค Exports
CSV files are written in the ๐ Downloads & exports folder (named plex-, UTF-8 for
Numbers / Excel) and shown in Finder:
| From | Export |
|---|---|
| Library section | every movie / episode / track with file, size, quality, views, ratings, ids |
| History, Statistics โบ Plays | every play (date, user, device, platform, library, title) |
| Statistics | libraries, bandwidth, media quality |
| Sessions, Settings | running sessions, every setting |
| Account | devices, users, watchlist |
| Presets | your presets |
| Plex Help โบ Workflow Cache & Logs | workflow logs (zip with versions) to attach to a GitHub issue |
Plex Presets: manage presets to rapidly search medias
1. Create a preset
- From Plex Search: the last row, ๐พ Save this search as a preset, asks only for a
title(and an optional/subtitle). - Or press โ on
Add a new preset, input avalue(filters with long names or aliases), then atitleand an optionalsubtitleseparated by a/.
2. Use and organize presets
| Key | Action |
|---|---|
| โ | open Plex Search with the preset |
| โโ | edit page: title/subtitle, value (โC copies it), duplicate, move up / down, delete |
| โฅโ | delete (with confirmation) |
| โโ | duplicate |
| โงโ | move up |
Presets with unknown filters are flagged with โ ๏ธ. The list can be exported to CSV.


Plex Help: workflow configuration + filter & sort options
Getting Started (for new users), Keyboard Shortcuts (your current shortcuts and keywords), workflow
cache (with the plex.log file and Export Workflow Logs), data and filter alias.

Filters, fields and sorts options are generated from the library sections of all your servers. They vary with your medias and agents.
1. Filters
Filters can be aliased, see section
4. Aliasbelow
Plex filters are applied by typing filterName=value. Use / to separate them. Find the list of filters under
each library section of your servers.
Example: libtype=movie/actor=adam driver. It returns movies with Adam Driver.

2. Fields (advanced filters)
Plex fields (or advanced filters) are applied by typing advancedFilters={ (or af={):
- Use
/to separate advanced filters from other filters. - Use them along with a
libtype. - Provide a valid Python dict or JSON. Double quotes
"and single quotes'are valid. The value is parsed, never executed.
To know more on how to use these filters, check the Python-PlexAPI documentation.
Example: libtype=episode/advancedFilters={'show.title': 'one piece', 'episode.index': '1074'}. It returns
episodes where episode number is 1074 and the title of the show contains one piece.

3. Sorts
Sort results by typing sort=sortName:dir (or so=sortName:dir). Direction can be :asc or :desc.
Example: libtype=movie/sort=originallyAvailableAt:desc displays movies from the most recent to the oldest.

4. Alias
Aliases let you write filters faster: libtype becomes lt, studio becomes st... Aliases and long names
are always accepted; the ๐ Use alias option only changes what the workflow displays.
Press โ on a filter to change its alias. The alias.json file is located in the ๐ Data folder
(~/Library/Application Support/Alfred/Workflow Data/com.benjamino.plex by default). New filters shipped with an
update are added to your file automatically, your custom aliases are kept.
Example: af={'addedAt>>': '30d'}/lt=show. It returns shows added or containing new elements (seasons,
episodes) during the last 30 days.

๐งฉ How it works
Workflow diagram
The diagram is a small hub. Every row of the workflow sets {var:action} and the
Router sends it to the right place:
Plex (keyword) โโโ
Plex Search โโโค
Plex Discover โโโค
Grid View โโโผโโโถ Router {var:action} โโโถ browse ยท search ยท discover ยท grid ยท ask ยท open ยท reveal ยท mtv
dispatch โโโ โ โโถ details โโโถ Text View (media sheet)
โฒ โโโโถ run โโโถ Run Script (main.py run) โโโถ dispatch (next step)
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
grid โโโถ Run Script (main.py grid) โโโถ Grid View (posters) โโโถ Router
ask โโโถ Plex Prompt (Script Filter with a Return row) โโโถ Router
run โโโถ Run Script + loading page (Alfred stays open until the result)
Run Script โโโถ Arg and Vars {var:notify_text} โโโถ Post Notification (only when the text is not empty)
| Variable | Role |
|---|---|
action |
browse, search, discover, grid, ask, run, details, open, reveal, mtv (or done) |
nav |
page path, e.g. servers/ |
cmd / payload |
background command and its JSON parameters |
prompt_title / prompt_subtitle |
text of the prompt (ask) |
back |
history: JSON stack of the screens you came from (Return pops it) |
confirm |
Yes / Cancel page content |
run_id / loading_label |
status file and text of the loading page |
state |
sort and filters of the library browser |
details_file |
Markdown sheet shown by the Text View |
notify_title / notify_text |
notification posted by Alfred at the end of a long command or of an error (empty when ๐ Notifications is unticked) |
A command (python3 main.py run) decides the next step (show a page, ask another question...) by printing
Alfred variables, which go back to the Router through the dispatch trigger.
Code
src/
โโโ main.py # entry point (checks Python version)
โโโ alfred_plex/
โ โโโ cli.py # browse | search | discover | run
โ โโโ alfred.py # Item / Feedback / Intent (actions as Alfred variables)
โ โโโ nav.py # page paths + router
โ โโโ settings.py # user configuration
โ โโโ store.py # accounts / servers / presets / alias JSON files
โ โโโ plex.py # python-plexapi: config, connections, caches
โ โโโ context.py # per run context
โ โโโ filters.py # search query parser
โ โโโ media.py # plex medias โ Alfred rows
โ โโโ system.py # command messages, notification text, sound, logs
โ โโโ stats.py # plays, bandwidth, libraries, quality (pure functions)
โ โโโ export.py # CSV exports + logs archive
โ โโโ library.py # library browser state (sort, filters)
โ โโโ posters.py # posters cache for the Grid View
โ โโโ details.py # Markdown media sheet for the Text View
โ โโโ views/ # pages (menu, library, grid, accounts, servers, stats, media, presets, help, search, discover)
โ โโโ commands/ # background actions
โโโ lib/ # python-plexapi 4.18.3 + dependencies (pure python)
โโโ info.plist
๐งช Development
# run the tests (no network needed: plexapi parses real Plex XML from a fake HTTP session)
python3 -m pip install pytest ruff
python3 -m pytest
python3 -m ruff check src/alfred_plex src/main.py tests
# update the bundled dependencies
cd src && ./update.sh
Try a page from a terminal (from the src folder):
nav=help python3 main.py browse | python3 -m json.tool
โ๏ธ License
MIT License ยฉ Benjamin Oddou