mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-15 21:46:29 +03:00
Magnus Hedemarkandfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2140d0d58d
Full lastfm-model rebuild of the jellyfin skill against the 12.0-era OpenAPI spec, core-dev authorization guidance, and server source: - Document the researched auth sequence end to end: complete pre-token Authorization: MediaBrowser Client/Device/DeviceId/Version header required by POST /Users/AuthenticateByName (400 "Error processing request." without it), AccessToken returned, then Token= on the same header (legacy X-Emby-Token deprecated, disableable since 10.11, targeted for removal at 12.0). - Extend scripts/jellyfin: new `login` subcommand demonstrating the pre-token header and printing session exports (password via stdin/prompt/env only), seasons/episodes TV navigation, next-up --series-id, browse --user-id (userId is required on non-API-key auth per the ItemsController guard), modern Token= header transport with X-Emby-Token fallback, 503 Retry-After handling, search Id/deprecated-ItemId fallback. - Add 5 cited reference files (auth/sessions, endpoint catalog, user-scoping matrix, gotchas field guide, worked recipes) plus quick-connect; all cite api.jellyfin.org and live-verified sources. - Upgrade relocated scripts/test_jellyfin_cli.py to the double-runner standard: 24 tests (was 8) covering help, argument errors, dry-run, mocked login header sequence, TV navigation, search-id fallback, and jq-executed pipeline-consumability chains; zero egress proven via proxy-trap rerun. - Add evals/evals.json (6 cases incl. emby-install-not-for-jellyfin negative probe); rewrite SKILL.md (224 lines) and README; sync root README blurb and skill-triggers row; regenerate marketplace.json and llms.txt (description-embedding artifacts). Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# Jellyfin Media Server from the Terminal
|
|
|
|
Query your Jellyfin media library — recently added movies and episodes, search and inspect
|
|
items, walk series, seasons, and episodes, browse library contents, see next-up episodes,
|
|
log in as a user, and check server stats.
|
|
|
|
## Why Install This Skill
|
|
|
|
When your agent loads this skill, it can **navigate your home media server** without
|
|
opening a browser. That means:
|
|
|
|
- **See what's new** — recently added movies and TV episodes, filtered server-side
|
|
- **Search your library** — find any movie, show, or episode by keyword
|
|
- **Navigate series** — walk a show's seasons and episodes, and see what's next unwatched
|
|
- **Browse collections** — list your libraries and page through everything in them
|
|
- **Authenticate properly** — log in as a user (or use Quick Connect) without fumbling
|
|
Jellyfin's unusual `MediaBrowser` authorization header, which trips up most scripts
|
|
- **Check server details** — server name, version, operating system, user count, counts
|
|
|
|
Every command is read-only (plus a `login` helper), and `--dry-run` previews any request
|
|
without touching the network.
|
|
|
|
## What You Get
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `SKILL.md` | Complete command reference with setup, gotchas, and recipes |
|
|
| `scripts/jellyfin` | CLI for Jellyfin API operations (`--json`, `--dry-run`) |
|
|
| `scripts/test_jellyfin_cli.py` | Offline test suite (all HTTP mocked) |
|
|
| `references/auth-and-sessions.md` | The MediaBrowser header scheme, login flow, token channels, deprecation timeline |
|
|
| `references/endpoint-catalog.md` | Endpoint-by-endpoint parameter and response-shape catalog |
|
|
| `references/user-scoping-and-errors.md` | Which calls need a user id, and why queries 400/404 without one |
|
|
| `references/gotchas-field-guide.md` | Wire-level failure signatures and version differences |
|
|
| `references/worked-recipes.md` | Multi-step curl/jq and CLI workflows |
|
|
| `references/quick-connect.md` | Passwordless Quick Connect login |
|
|
| `evals/evals.json` | Behavioral eval cases including negative triggers |
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
scripts/jellyfin --help
|
|
export JELLYFIN_URL="http://your-server:8096"
|
|
export JELLYFIN_API_KEY="your-api-key" # Dashboard → API Keys
|
|
export JELLYFIN_USER_ID="your-jellyfin-user-id" # required by user-scoped commands
|
|
```
|
|
|
|
```bash
|
|
scripts/jellyfin search --query "dune" --type Movie --json
|
|
scripts/jellyfin recent --movies --limit 5
|
|
```
|
|
|
|
No API key yet? Log in as a user instead — the script sends the pre-token
|
|
`Authorization: MediaBrowser Client=..., Device=..., DeviceId=..., Version=...` header
|
|
that `POST /Users/AuthenticateByName` requires and prints the values to export:
|
|
|
|
```bash
|
|
scripts/jellyfin login --username alice --prompt
|
|
```
|
|
|
|
## Triggers
|
|
|
|
Load this when asking about Jellyfin, media server content, recently added movies or TV,
|
|
next-up episodes, browsing your home media library, or Jellyfin API authentication.
|
|
|
|
## Requirements
|
|
|
|
Python 3.8+ with `requests`. A running Jellyfin server (10.8+ behaviors assumed).
|
|
Authentication: an API key (Dashboard → API Keys), a user access token via `login`, or
|
|
Quick Connect. User-scoped commands also need a Jellyfin user id.
|