Merge pull request #243 from robbeverhelst/robbeverhelst/jellyfin-images

feat(jellyfin): add artwork commands for fixing missing or poor covers

Author: robbeverhelst

README.md

@@ -11,7 +11,7 @@
 
   <br />
 
-  <img src="./docs/vhs/hero.gif" alt="tsarr doctor — eight services, one terminal" />
+  <img src="./docs/vhs/hero.gif" alt="tsarr doctor — your whole media stack in one terminal" />
 
 </div>
 

docs/cli-commands.md

@@ -375,6 +375,11 @@ tsarr jellyfin <resource> <action> [args]
 | `item` | `latest` | `--user <v> [--limit <n>]` | List recently added items |
 | `item` | `nextup` | `--user <v> [--limit <n>]` | List next-up episodes |
 | `item` | `resume` | `--user <v> [--limit <n>]` | List in-progress (resumable) items |
+| `image` | `list` | `--id <v>` | Artwork an item has, with dimensions — use to spot missing or poor covers |
+| `image` | `remote` | `--id <v> [--type <v>] [--provider <v>] [--all-languages] [--limit <n>]` | Artwork candidates from metadata providers |
+| `image` | `providers` | `--id <v>` | Artwork providers available for an item |
+| `image` | `set` | `--id <v> --type <v> --url <v>` | Attach artwork from a URL, replacing the existing image |
+| `image` | `delete` | `--id <v> --type <v> [--index <n>]` | Remove artwork (confirms) |
 | `watched` | `status` | `--id <v> --user <v>` | Show watched state for an item |
 | `watched` | `mark` | `--id <v> --user <v>` | Mark an item as played |
 | `watched` | `unmark` | `--id <v> --user <v>` | Mark an item as unplayed |
@@ -411,6 +416,13 @@ tsarr jellyfin <resource> <action> [args]
 Jellyfin returns PascalCase JSON, so table columns and `--select` use PascalCase
 field names (`Id`, `Name`, `Type`) rather than the camelCase used by Servarr services.
 
+**Artwork:** `image set --url` accepts any reachable image URL, not just the
+candidates from `image remote`. Note that `image remote` reports `Width`/`Height`
+on Jellyfin 10.11 but **not on 12.0**, even though the API schema declares them —
+rank candidates by `CommunityRating` when dimensions are absent. The image
+*serving* endpoints (`GET /Items/{id}/Images/...`, which return raw bytes) are
+deliberately not wrapped.
+
 **Not available:** there is no `playlist get` or `playlist move`. Jellyfin's
 `GetPlaylist` and `MoveItem` endpoints require a user-context token and expose no
 `userId` parameter, so they return HTTP 400 under the API-key authentication tsarr

docs/cli-getting-started.md

@@ -5,7 +5,7 @@ group: CLI
 
 # CLI Getting Started
 
-TsArr includes a command-line interface for interacting with Servarr services directly from your terminal.
+TsArr includes a command-line interface for interacting with your media stack directly from your terminal — Radarr, Sonarr, Lidarr, Readarr, Prowlarr, Bazarr, qBittorrent, Seerr and Jellyfin.
 
 ## Installation
 

docs/cli.md

@@ -745,6 +745,13 @@ tsarr jellyfin item latest --user <userId>     # Recently added
 tsarr jellyfin item nextup --user <userId>     # Next-up episodes
 tsarr jellyfin item resume --user <userId>     # In-progress items
 
+# Artwork — fix a missing or poor cover
+tsarr jellyfin image list --id <itemId>              # what artwork exists, with dimensions
+tsarr jellyfin image remote --id <itemId> --type Primary --limit 10
+tsarr jellyfin image set --id <itemId> --type Primary --url "<url>"
+tsarr jellyfin image delete --id <itemId> --type Primary
+tsarr jellyfin image providers --id <itemId>
+
 # Watched state
 tsarr jellyfin watched status --id <itemId> --user <userId>
 tsarr jellyfin watched mark --id <itemId> --user <userId>

docs/usage.md

@@ -1,6 +1,6 @@
 # Usage Guide
 
-This guide provides comprehensive documentation for using the TsArr TypeScript SDK to interact with Servarr APIs.
+This guide provides comprehensive documentation for using the TsArr TypeScript SDK to interact with Radarr, Sonarr, Lidarr, Readarr, Prowlarr, Bazarr, qBittorrent, Seerr and Jellyfin.
 
 ## Installation
 
@@ -365,6 +365,10 @@ const devRadarr = new RadarrClient({
 });
 ```
 
+Every client owns its configuration, so instances of the same service never
+interfere with each other — `prodRadarr` keeps its base URL and API key when
+`devRadarr` is constructed. The same holds for `updateConfig()` on one instance.
+
 ### Custom Headers and Options
 
 ```typescript

package.json

@@ -93,7 +93,7 @@
       "types": "./dist/clients/jellyfin-types.d.ts"
     }
   },
-  "description": "Type-safe TypeScript SDK for Servarr APIs (Radarr, Sonarr, etc.)",
+  "description": "Type-safe TypeScript SDK and CLI for your media stack (Radarr, Sonarr, Lidarr, Readarr, Prowlarr, Bazarr, qBittorrent, Seerr, Jellyfin)",
   "engines": {
     "node": ">=24.18.0"
   },

scripts/jellyfin-smoke.ts

@@ -244,6 +244,92 @@ for (const target of TARGETS) {
     ]);
   }
 
+  // ---- artwork ------------------------------------------------------------
+  if (movieId) {
+    check(
+      'image list',
+      ['jellyfin', 'image', 'list', '--id', movieId, '--json'],
+      expectField('ImageType')
+    );
+    const remoteOut = check('image remote', [
+      'jellyfin',
+      'image',
+      'remote',
+      '--id',
+      movieId,
+      '--type',
+      'Primary',
+      '--limit',
+      '5',
+      '--json',
+    ]);
+    const candidates = json(remoteOut ?? '[]') ?? [];
+    check('image providers', ['jellyfin', 'image', 'providers', '--id', movieId, '--json']);
+
+    if (candidates.length) {
+      // Rank by resolution where the server reports it (10.11) and by rating
+      // otherwise (12.0 omits Width/Height).
+      const ranked = [...candidates].sort((a: any, b: any) =>
+        typeof a.Width === 'number'
+          ? (b.Width ?? 0) - (a.Width ?? 0)
+          : (b.CommunityRating ?? 0) - (a.CommunityRating ?? 0)
+      );
+      check('image set from url', [
+        'jellyfin',
+        'image',
+        'set',
+        '--id',
+        movieId,
+        '--type',
+        'Primary',
+        '--url',
+        ranked[0].Url,
+      ]);
+      check(
+        'image list shows the new cover',
+        ['jellyfin', 'image', 'list', '--id', movieId, '--json'],
+        stdout => {
+          const images = json(stdout) ?? [];
+          return images.some((i: any) => i.ImageType === 'Primary')
+            ? null
+            : 'Primary missing after set';
+        }
+      );
+      check('image delete', [
+        'jellyfin',
+        'image',
+        'delete',
+        '--id',
+        movieId,
+        '--type',
+        'Primary',
+        '--yes',
+      ]);
+      check(
+        'image list shows it gone',
+        ['jellyfin', 'image', 'list', '--id', movieId, '--json'],
+        stdout => {
+          const images = json(stdout) ?? [];
+          return images.some((i: any) => i.ImageType === 'Primary')
+            ? 'Primary still present'
+            : null;
+        }
+      );
+      // Put it back so reruns start from a known state.
+      cli([
+        'jellyfin',
+        'image',
+        'set',
+        '--id',
+        movieId,
+        '--type',
+        'Primary',
+        '--url',
+        ranked[0].Url,
+      ]);
+    }
+  }
+
   // ---- search -------------------------------------------------------------
   check(
     'search query',

skills/tsarr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tsarr
-description: Manage home media services through TsArr from OpenClaw. Use for Radarr, Sonarr, Lidarr, Readarr, Prowlarr, Bazarr, qBittorrent, Seerr, and Jellyfin tasks such as checking health, inspecting queues and history, browsing libraries, searching, adding, editing, deleting items, viewing profiles, tags, and root folders, managing torrents, managing media requests, triggering library scans, reading watched state, checking active playback sessions, and checking TsArr configuration.
+description: Manage home media services through TsArr from OpenClaw. Use for Radarr, Sonarr, Lidarr, Readarr, Prowlarr, Bazarr, qBittorrent, Seerr, and Jellyfin tasks such as checking health, inspecting queues and history, browsing libraries, searching, adding, editing, deleting items, viewing profiles, tags, and root folders, managing torrents, managing media requests, triggering library scans, reading watched state, checking active playback sessions, fixing missing or poor cover images, and checking TsArr configuration.
 metadata:
   openclaw:
     requires:

skills/tsarr/references/common-workflows.md

@@ -197,6 +197,58 @@ Jellyfin output is PascalCase, so extract fields accordingly:
 tsarr jellyfin item list --type Movie --json --select Id,Name
 ```
 
+## Fix a missing or poor cover image
+
+When someone says a title has no cover, or a bad one, resolve it in four steps.
+Never guess an item ID — look it up.
+
+```bash
+# 1. Find the item
+tsarr jellyfin item list --search "Pokemon" --type Movie --json --select Id,Name,ProductionYear
+
+# 2. Inspect what artwork it has. No Primary row means no cover; a small
+#    Width/Height means a poor one.
+tsarr jellyfin image list --id <itemId> --json
+
+# 3. List candidates from the metadata providers
+tsarr jellyfin image remote --id <itemId> --type Primary --limit 10 --json
+
+# 4. Apply the chosen one
+tsarr jellyfin image set --id <itemId> --type Primary --url "<url>"
+```
+
+Choosing a candidate:
+
+- Prefer higher `Width`/`Height`, then higher `CommunityRating`.
+- **`Width`/`Height` are absent on Jellyfin 12.0** (present on 10.11), even
+  though the API schema declares them. When they are missing, rank by
+  `CommunityRating` and `VoteCount` instead.
+- `Language` matters for posters with title text; pass `--all-languages` to
+  widen the search.
+
+`--url` accepts **any reachable image URL**, not only provider candidates, so a
+cover found elsewhere can be applied directly:
+
+```bash
+tsarr jellyfin image set --id <itemId> --type Primary --url "https://example.com/poster.jpg"
+```
+
+Other artwork types work the same way — `Backdrop`, `Logo`, `Thumb`, `Banner`.
+To drop a bad image without replacing it:
+
+```bash
+tsarr jellyfin image delete --id <itemId> --type Primary --yes
+```
+
+To sweep a whole library for missing covers:
+
+```bash
+for id in $(tsarr jellyfin item list --type Movie --quiet); do
+  tsarr jellyfin image list --id "$id" --json \
+    | grep -q '"Primary"' || echo "no cover: $id"
+done
+```
+
 ## Configuration checks
 
 When a command fails unexpectedly, inspect TsArr’s merged configuration:

skills/tsarr/references/service-cheatsheet.md

@@ -162,36 +162,73 @@ Seerr uses API key authentication. Configure via `tsarr config init` or environm
 
 ## Jellyfin
 
-Use for media server tasks: trigger library scans, read watched state, and check who is streaming.
+Use for media server tasks: trigger library scans, read watched state, see who is streaming, control playback, manage playlists and collections, and fix artwork.
+
+Full command surface:
 
 ```bash
-tsarr jellyfin system status --json
 tsarr jellyfin library refresh
-tsarr jellyfin library folders --json
-tsarr jellyfin item list --type Movie --json
-tsarr jellyfin item list --search "The Matrix" --limit 10 --json
-tsarr jellyfin item counts --json
-tsarr jellyfin item get --id <itemId> --user <userId> --json
-tsarr jellyfin watched status --id <itemId> --user <userId> --json
-tsarr jellyfin watched mark --id <itemId> --user <userId>
-tsarr jellyfin session list --json
-tsarr jellyfin session pause --id <sessionId>
-tsarr jellyfin session message --id <sessionId> --text "Maintenance in 5 minutes"
-tsarr jellyfin playlist create --name "Friday" --user <userId> --json
-tsarr jellyfin playlist items --id <playlistId> --user <userId> --json
-tsarr jellyfin collection create --name "Sci-Fi" --items <a,b> --json
-tsarr jellyfin user list --json
-tsarr jellyfin task list --json
-tsarr jellyfin search query --query "The Matrix" --json
+tsarr jellyfin library folders
+tsarr jellyfin library add --name <name> [--collection-type <collection-type>] [--paths <paths>] [--refresh]
+tsarr jellyfin library remove --name <name>
+tsarr jellyfin item list [--search <search>] [--type <type>] [--parent <parent>] [--user <user>] [--played] [--limit <limit>]
+tsarr jellyfin item get --id <id> --user <user>
+tsarr jellyfin item refresh --id <id> [--mode <mode>] [--replace-metadata] [--replace-images]
+tsarr jellyfin item delete --id <id>
+tsarr jellyfin item counts [--user <user>]
+tsarr jellyfin item latest --user <user> [--limit <limit>]
+tsarr jellyfin item nextup --user <user> [--limit <limit>]
+tsarr jellyfin item resume --user <user> [--limit <limit>]
+tsarr jellyfin image list --id <id>
+tsarr jellyfin image remote --id <id> [--type <type>] [--provider <provider>] [--all-languages] [--limit <limit>]
+tsarr jellyfin image providers --id <id>
+tsarr jellyfin image set --id <id> --type <type> --url <url>
+tsarr jellyfin image delete --id <id> --type <type> [--index <index>]
+tsarr jellyfin watched status --id <id> --user <user>
+tsarr jellyfin watched mark --id <id> --user <user>
+tsarr jellyfin watched unmark --id <id> --user <user>
+tsarr jellyfin watched favorite --id <id> --user <user>
+tsarr jellyfin watched unfavorite --id <id> --user <user>
+tsarr jellyfin session list [--active-within <active-within>]
+tsarr jellyfin session play --id <id> --items <a,b> [--mode <mode>] [--position <position>]
+tsarr jellyfin session pause --id <id>
+tsarr jellyfin session unpause --id <id>
+tsarr jellyfin session stop --id <id>
+tsarr jellyfin session seek --id <id> --position <position>
+tsarr jellyfin session message --id <id> --text <text> [--header <header>] [--timeout <timeout>]
+tsarr jellyfin session command --id <id> --command <command>
+tsarr jellyfin session system --id <id> --command <command>
+tsarr jellyfin session display --id <id> --item <item> --name <name> --type <type>
+tsarr jellyfin session add-user --id <id> --user <user>
+tsarr jellyfin session remove-user --id <id> --user <user>
+tsarr jellyfin playlist create --name <name> --user <user> [--items <a,b>] [--type <type>]
+tsarr jellyfin playlist items --id <id> --user <user> [--limit <limit>]
+tsarr jellyfin playlist add --id <id> --items <a,b> --user <user>
+tsarr jellyfin playlist remove --id <id> --entries <a,b>
+tsarr jellyfin collection create --name <name> [--items <a,b>] [--parent <parent>]
+tsarr jellyfin collection add --id <id> --items <a,b>
+tsarr jellyfin collection remove --id <id> --items <a,b>
+tsarr jellyfin user list
+tsarr jellyfin user get --id <id>
+tsarr jellyfin task list
+tsarr jellyfin task start --id <id>
+tsarr jellyfin task stop --id <id>
+tsarr jellyfin search query --query <query> [--type <type>] [--limit <limit>]
+tsarr jellyfin system status
+tsarr jellyfin system activity [--limit <limit>]
 ```
 
-Jellyfin uses API key authentication. Configure via `tsarr config init` or environment variables `TSARR_JELLYFIN_URL` and `TSARR_JELLYFIN_API_KEY`. Get a key from Dashboard -> Advanced -> API Keys.
+Add `--json` to any command when extracting values.
 
-Playlists are user-owned: `playlist create`, `items` and `add` all require `--user`. There is no `playlist get` or `playlist move` — those Jellyfin endpoints need a user-context token and reject API keys; use `tsarr jellyfin item get --id <playlistId> --user <userId>` instead.
+Jellyfin uses API key authentication. Configure via `tsarr config init` or environment variables `TSARR_JELLYFIN_URL` and `TSARR_JELLYFIN_API_KEY`. Get a key from Dashboard -> Advanced -> API Keys.
 
 **Important:** Jellyfin returns PascalCase JSON (`Id`, `Name`, `Type`, `Items`), unlike the camelCase used by the Servarr services. Use PascalCase when parsing output or passing `--select`.
 
-`--user <userId>` is **required** on `item get`, `item latest`, `item nextup`, `item resume` and all `watched` commands. Jellyfin's spec marks it optional but the server returns 400 without it. Get IDs from `tsarr jellyfin user list --json`.
+`--user <userId>` is **required** on `item get`, `item latest`, `item nextup`, `item resume` and all `watched` and `playlist` commands. Jellyfin's spec marks it optional but the server returns 400 without it. Get IDs from `tsarr jellyfin user list --json`.
+
+There is no `playlist get` or `playlist move` — those Jellyfin endpoints need a user-context token and reject API keys; use `tsarr jellyfin item get --id <playlistId> --user <userId>` instead.
+
+See "Fix a missing or poor cover image" in common-workflows.md for the artwork workflow.
 
 ## Multi-instance services