β¨ Welcome to the Alfred Plex repository: An Alfred Workflow β¨
- 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- 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).
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.
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.
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).
- 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.
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.
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.
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.
Press β on a media (Plex Search, Plex Discover, libraries, recently added, posters...): Alfred shows its
actions panel for the media title (Metropolis (1927) Β· 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... |
| 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.
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.
Servers are searched in parallel, so adding servers doesn't make the search slower.
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.
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.
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.
If you don't have VLC / IINA on your mac, install it with homebrew:
brew install --cask vlc
brew install --cask iinaThe workflow uses their command line tools (vlc / iina), found in /opt/homebrew/bin or /usr/local/bin.
Check them with:
which vlc
which iinaIf 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.
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).
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.
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.
CSV files are written in the π Downloads & exports folder (named plex-<server>-<kind>-<date>.csv, 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 |
- 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/.
| 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
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.
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.
Plex fields (or advanced filters) are applied by typing advancedFilters={<FILTER>} (or af={<FILTER>}):
- 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.
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.
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.
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/<machineId>/settings/general |
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.
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
# 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.shTry a page from a terminal (from the src folder):
nav=help python3 main.py browse | python3 -m json.toolThe screenshots only show films that are free to use: public domain films and the Blender open movies (Big Buck Bunny, Elephants Dream, Sintel, Tears of Steel, Cosmos Laundromat: CC BY, Β© Blender Foundation | blender.org). Posters come from Wikimedia Commons.
MIT License Β© Benjamin Oddou








