magnus919_agent-skills/jellyfin-cli/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
jellyfin-cli	Query your Jellyfin media server from the terminal — recently added media, search, item details, next-up episodes, library browsing, server info, and stats. Use when the user asks about Jellyfin, media server, movies, TV shows, next episodes, or their media library.	MIT	Requires JELLYFIN_URL (default http://localhost:8096) and JELLYFIN_API_KEY env vars; `recent`, `next-up`, and `item` also require JELLYFIN_USER_ID or --user-id. Python 3.8+ and the `requests` library. Generate an API key at Dashboard → API Keys in the Jellyfin admin panel.	tags sources jellyfin, media-server, movies, tv, episodes, recently-added, library, home-media, api-client https://jellyfin.org/docs/general/clients/api, https://jellyfin.org/downloads

jellyfin-cli — Jellyfin Media Server from the Terminal

Query recently added movies and TV episodes, search and inspect media, browse libraries, see next-up episodes, check server info, and view library statistics — all from your Jellyfin server's REST API.

Setup

1. Make sure your Jellyfin server is running and accessible.
2. Generate an API key in the Jellyfin Dashboard → API Keys → + to create a new key.
3. Set these environment variables:

export JELLYFIN_URL="http://your-server:8096"   # include protocol and port
export JELLYFIN_API_KEY="your-api-key-here"
export JELLYFIN_USER_ID="your-jellyfin-user-id" # required by recent, next-up, and item

Run the bundled CLI as scripts/jellyfin-cli. --help and --dry-run work without credentials.

Essential Commands

info — Server information

scripts/jellyfin-cli info                           # server name, version, OS, user count
scripts/jellyfin-cli info --json                    # machine-readable
scripts/jellyfin-cli --dry-run info                 # preview API requests

Shows: server name, version, operating system, number of users.

recent — Recently added media

scripts/jellyfin-cli recent                         # last 10 items added
scripts/jellyfin-cli recent --limit 20              # more results
scripts/jellyfin-cli recent --movies                # only recently added movies
scripts/jellyfin-cli recent --episodes              # only recently added episodes
scripts/jellyfin-cli recent --user-id USER_ID       # override JELLYFIN_USER_ID
scripts/jellyfin-cli recent --movies --limit 5      # top 5 recently added movies
scripts/jellyfin-cli recent --json                  # machine-readable

Uses Jellyfin's current /Items/Latest endpoint. --movies and --episodes send includeItemTypes to the server, so the requested limit applies to the selected media type. Shows: name, type (Movie/Episode), production year, series name (for episodes), date added.

search — Search your media library

scripts/jellyfin-cli search --query "dune"                # search everything
scripts/jellyfin-cli search --query "dune" --type Movie   # movies only
scripts/jellyfin-cli search --query "star trek" --type Series,Episode
scripts/jellyfin-cli search --query "inception" --limit 5 # top 5 results
scripts/jellyfin-cli search --query "dune" --json         # machine-readable

The --type flag accepts a comma-separated list of item types (e.g. Movie,Series,Episode).

Navigation — Inspect media and browse libraries

scripts/jellyfin-cli search --query "dune" --type Movie    # find an item ID
scripts/jellyfin-cli item --id ITEM_ID                      # inspect that item
scripts/jellyfin-cli libraries                               # find a library ID
scripts/jellyfin-cli browse --library-id LIBRARY_ID --type Movie --limit 20
scripts/jellyfin-cli browse --library-id LIBRARY_ID --start-index 20
scripts/jellyfin-cli next-up --limit 10                      # next episodes for JELLYFIN_USER_ID
scripts/jellyfin-cli next-up --user-id USER_ID --json

Use search -> item to look up a result's metadata, and libraries -> browse to page through a collection. next-up returns the next unwatched episodes for the selected user. item and next-up require JELLYFIN_USER_ID or --user-id; all three commands are read-only.

libraries — List media libraries

scripts/jellyfin-cli libraries                     # all configured libraries
scripts/jellyfin-cli libraries --json              # machine-readable

Shows: library name, collection type (movies, tvshows, music, etc.), library ID.

stats — Library statistics

scripts/jellyfin-cli stats                         # movie, series, episode, song counts
scripts/jellyfin-cli stats --json                  # machine-readable

Shows: total count of movies, series, episodes, and songs in the library.

Global Flags

These flags work anywhere in the command — before or after the subcommand:

scripts/jellyfin-cli --json recent --limit 5               # JSON output
scripts/jellyfin-cli recent --limit 5 --json               # same result, after subcommand
scripts/jellyfin-cli --dry-run search --query "dune"       # preview request without API call

Flag	Effect
--json	Output machine-readable JSON instead of human-readable text
--dry-run	Show each request path and parameters without executing it

Known Gotchas

• JELLYFIN_URL must include protocol and port — Both are required, e.g. http://192.168.1.100:8096. A bare hostname or IP without http:// and :8096 will fail. The default is http://localhost:8096.
• User-scoped commands require an explicit user — Set JELLYFIN_USER_ID or pass --user-id USER_ID to recent, next-up, or item. The CLI never selects an administrator automatically. A real request without either value fails before network access; dry-run previews the request with a null user ID.
• Recent type filtering is server-side — --movies and --episodes become the /Items/Latest includeItemTypes parameter before limit; no local filtering is applied.
• Search type values — The --type flag for search uses Jellyfin item type names (e.g. Movie, Series, Episode, MusicArtist, MusicAlbum). Multiple types are comma-separated without spaces.
• API key location — Generate the key in the Jellyfin Dashboard under Dashboard → API Keys. The key is sent as the X-Emby-Token header.
• Lazy auth — --help and --dry-run work even when JELLYFIN_URL and JELLYFIN_API_KEY are not set. Dry-run reports request paths and parameters but never sends credentials or makes a network call.
• No pagination — Every command returns a single page of results. The CLI does not auto-paginate beyond the first response. Use --limit to control result size.

References

• scripts/jellyfin-cli — The bundled read-only CLI binary with --json, --dry-run, and lazy authentication.
• Jellyfin API Docs — Official API documentation.
• Jellyfin Downloads — Server download and setup guide.