scripts/plex/README.md

plex

Operational scripts for the Plex Media Server running as a container on odin.

Reached at https://plex.bergerhouse.net (DNS resolves to odin's LAN address 192.168.90.103, routed over the tailnet — see ../docs/odin-access.md).

Script	What it does	Mutates?
bin/plex-health	Read-only health report: server, updates, libraries, unmatched media, Butler tasks, active streams	no
bin/poster-audit	Finds items whose poster is missing or does not resolve	no
bin/poster-repair	Re-selects the poster for items the audit flags	yes

known-issues.conf lists findings that have been reviewed and accepted. plex-health still reports them, but as [info] rather than [warn], so a known-and-accepted item stops making the whole run read as failing. Nothing is ever suppressed silently.

Prerequisites

• Where it runs: this workstation (dev), targeting odin over Tailscale. Nothing needs to be installed on odin itself — everything goes through the Plex HTTP API.
• Interpreters: bash 4+
• External tools: curl, jq
• Access needed: an admin X-Plex-Token. No SSH to odin is required.

Unlike odin's myunraid.net vhost, plex.bergerhouse.net presents a TLS chain that verifies cleanly from dev — PLEX_INSECURE stays 0 and no -k is needed.

Configuration

Copy .env.example to .env and fill it in. .env is gitignored repo-wide.

Variable	Required	Description
PLEX_URL	yes	Base URL of the server. Use https:// — plain HTTP 302-redirects.
PLEX_TOKEN	yes	Admin X-Plex-Token.
PLEX_INSECURE	no	1 to skip TLS verification. Not needed for PLEX_URL above.
PLEX_TIMEOUT	no	Per-request timeout in seconds (default 30).
POSTER_JOBS	no	Parallel HTTP checks during a poster scan (default 8).

To get a token: Plex Web → any library item → ⋯ → Get Info → View XML, then copy the X-Plex-Token query parameter out of the URL that opens.

The remaining ODIN_* and UNRAID_* variables in .env.example are placeholders for future scripts that need filesystem or host-level access. Nothing here uses them yet.

Usage

bin/plex-health                      # health report (exit 0 ok / 1 warn / 2 fail)
bin/plex-health --posters            # also check every poster (slow: 1 request per item)

bin/poster-audit                     # what is broken in TV Shows
bin/poster-audit --section Movies    # any library, by title or id
bin/poster-audit --json              # machine-readable

bin/poster-repair --dry-run          # preview, changes nothing
bin/poster-repair                    # apply
bin/poster-repair --limit 5          # apply to the first 5 only

A full TV Shows scan makes ~283 HTTP requests and takes a couple of minutes. The scan dominates the runtime, not the repair.

Behaviour notes

• Idempotent: yes. poster-repair only touches items whose poster does not currently resolve, so a second run repairs nothing. plex-health never writes.
• Destructive operations: none. poster-repair selects a poster that is already in the item's metadata bundle — no image is downloaded, deleted, or overwritten, and no other metadata field is touched. Items with a working poster are skipped, so a manually-chosen poster is never replaced.
• --allow-remote is the one exception: for an item with no locally-cached poster it pulls one from the metadata agent over the internet, which may select a different image than the one originally chosen. Off by default.
• Scheduling: manual for now. plex-health is cron-safe and exit-code driven if you want it on a timer.

Gotchas

A missing poster has two distinct causes, and the Plex UI shows them identically. Checking metadata alone will tell you the library is fine when it is not:

• MISSING — the item has no thumb field at all.
• BROKEN — the item has a thumb field, but fetching that URL returns 404. This was 94 of the 100 affected shows. Any audit that only looks for absent fields misses almost all of them.

The failure is a lost database pointer, not a lost file. For a broken item, /library/metadata/<key>/posters still lists all the candidates — often 85+ of them — with the agent's own poster already downloaded into the bundle as a metadata:// entry. What is gone is the selected: true flag: every candidate reads selected: false, so the thumb URL resolves to nothing. A working item has exactly one candidate selected. Re-selecting the local candidate is therefore instant and needs no internet access.

Diagnose with the selected count, not the poster list length. An affected show has plenty of poster candidates; the count of selected ones is the signal.

PUT /library/metadata/<key>/poster?url=<candidate> needs the candidate's ratingKey, which for a local candidate is the metadata://posters/... string, not the /library/... path from the same object's key field.

Season and episode posters were not affected — only show-level ones, and only in the TV Shows library. Every other library was later checked in full (not sampled) and came back 100% clean. Worth re-checking rather than assuming if this recurs.

A matched show can be full of unmatched episodes. Checking only the top level of a library is not enough: Battlestar Galactica has a real plex://show/... GUID and looks healthy in a show-level audit, while all 74 of its episodes carry local:// GUIDs and display as "Episode 1", "Episode 2"… with no titles or artwork. plex-health therefore checks show, season, and episode level. The episode list for a library this size is a ~30 MB response — it is written to a temp file before parsing, never piped into jq.

The 2-minute tool timeout will kill a full repair run. Run it with nohup ... & and tail the log, or use --limit.