Jellyfin CLI

jellyfin-cli — Jellyfin Media Server from the Terminal

Query recently added movies and TV episodes, search your media library, list libraries, 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"

--help and --dry-run work without credentials (lazy auth).

Essential Commands

info — Server information

jellyfin-cli info                           # server name, version, OS, user count
jellyfin-cli info --json                    # machine-readable
jellyfin-cli --dry-run info                 # preview the API call

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

recent — Recently added media

jellyfin-cli recent                         # last 10 items added
jellyfin-cli recent --limit 20              # more results
jellyfin-cli recent --movies                # only recently added movies
jellyfin-cli recent --episodes              # only recently added episodes
jellyfin-cli recent --movies --limit 5      # top 5 recently added movies
jellyfin-cli recent --json                  # machine-readable

Shows: name, type (Movie/Episode), production year, series name (for episodes), date added.

search — Search your media library

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

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

libraries — List media libraries

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

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

stats — Library statistics

jellyfin-cli stats                         # movie, series, episode, song counts
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:

jellyfin-cli --json recent --limit 5               # JSON output
jellyfin-cli recent --limit 5 --json               # same result, after subcommand
jellyfin-cli --dry-run search --query "dune"       # preview without API call
jellyfin-cli --quiet info                          # suppress diagnostic output
jellyfin-cli --verbose libraries                   # verbose logging

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.
• Admin user auto-discovery — The recent command automatically discovers the first admin user on the server to fetch their recently added items. If no admin user exists (unusual), it returns "No admin user found."
• Episode filtering is post-query — The --episodes flag filters the "latest items" endpoint results by Type == "Episode" after fetching. This means the returned count may be smaller than --limit if there aren't enough episodes among the latest items. Similarly, --movies filters by Type == "Movie".
• 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. All other commands will fail immediately if the env vars are missing or invalid.
• 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 CLI binary. Built following the cli-builder patterns: non-interactive, --json, --dry-run, --quiet, --verbose, dual-output via emit(), lazy auth, structured logging.
• Jellyfin API Docs — Official API documentation.
• Jellyfin Downloads — Server download and setup guide.