Jellyfin Manager

February 10, 2026 · View on GitHub

A command-line tool for managing Jellyfin watched status, featuring backup/restore capabilities and missing episode detection using TVDB.

AI Disclaimer: Portions of this codebase were generated with the assistance of AI tools.

Features

Backup Watched Status: Export all watched movies and TV episodes to a JSON file
Restore Watched Status: Import watched status from a backup file to same or different user
Find Missing Episodes: Compare your Jellyfin library against TVDB to identify missing episodes
Multi-Platform Support: Available as a standalone binary or Docker container
Flexible Configuration: Command-line flags or environment variables

Quick Start

Using Docker (Recommended)

# Backup watched status
docker run --rm -v jellyfinbackup:/backup \
  docker.io/f0rc3/jellyfinmanager \
  -backup \
  -server "https://your.jellyfin.server" \
  -apikey "your-api-key" \
  -user "your-username"

# Restore watched status
docker run --rm -v jellyfinbackup:/backup \
  docker.io/f0rc3/jellyfinmanager \
  -restore \
  -server "https://your.jellyfin.server" \
  -apikey "your-api-key" \
  -user "your-username"

# Find missing episodes
docker run --rm \
  docker.io/f0rc3/jellyfinmanager \
  -find-missing \
  -server "https://your.jellyfin.server" \
  -apikey "your-api-key" \
  -user "your-username" \
  -tvdb-apikey "your-tvdb-api-key"

Using Binary

Download the latest release for your platform and run:

# Backup
./jellyfinmanager -backup -server "http://localhost:8096" -apikey "KEY" -user "USER"

# Restore
./jellyfinmanager -restore -server "http://localhost:8096" -apikey "KEY" -user "USER"

# Find missing episodes
./jellyfinmanager -find-missing -server "http://localhost:8096" \
  -apikey "KEY" -user "USER" -tvdb-apikey "TVDB_KEY"

Installation

Docker

Pull the pre-built image:

docker pull docker.io/f0rc3/jellyfinmanager

Or build locally:

docker build -t jellyfinmanager .

From Source

Requires Go 1.25 or later:

git clone https://github.com/forceu/jellyfinmanager.git
cd jellyfinmanager
go build -o jellyfinmanager

Configuration

Command-Line Flags

Flag	Description	Required
`-server`	Jellyfin server URL (e.g., `http://localhost:8096`)	Yes*
`-apikey`	Jellyfin API key	Yes*
`-user`	Jellyfin username	Yes*
`-tvdb-apikey`	TVDB API key (required for `-find-missing`)	For find-missing
`-file`	Backup file path (default: `jellyfin_watched_backup.json`)	No
`-backup`	Perform backup operation	**
`-restore`	Perform restore operation	**
`-find-missing`	Find missing episodes using TVDB	**
`-include-specials`	Include special episodes in missing episode check	No

* Can be set via environment variables
** One operation flag is required

Environment Variables

Instead of command-line flags, you can use:

JELLYFIN_SERVER - Jellyfin server URL
JELLYFIN_API_KEY - Jellyfin API key
JELLYFIN_USER - Jellyfin username
TVDB_API_KEY - TVDB API key

Getting API Keys

Jellyfin API Key

Log in to your Jellyfin server
Go to Dashboard → API Keys
Click "+" to create a new API key
Give it a name (e.g., "Jellyfin Manager") and save

TVDB API Key

Register at TheTVDB
Subscribe to an API plan (free tier available)
Generate an API key from your account settings

Usage Examples

Backup Watched Status

Create a backup of all watched movies and TV episodes:

jellyfinmanager -backup \
  -server "http://localhost:8096" \
  -apikey "your-api-key" \
  -user "username" \
  -file "backup.json"

The backup file contains:

Timestamp of backup creation
Server URL and user information
All watched items with metadata (provider IDs, names, dates)

Restore Watched Status

Restore watched status from a backup (useful when migrating servers or users):

jellyfinmanager -restore \
  -server "http://localhost:8096" \
  -apikey "your-api-key" \
  -user "username" \
  -file "backup.json"

The restore process:

Matches items using provider IDs (IMDB, TMDB, TVDB)
Falls back to name matching if provider IDs don't match
Skips items already marked as watched
Provides detailed progress and summary

Find Missing Episodes

Identify episodes that exist in TVDB but are missing from your Jellyfin library:

jellyfinmanager -find-missing \
  -server "http://localhost:8096" \
  -apikey "your-api-key" \
  -user "username" \
  -tvdb-apikey "your-tvdb-key"

Optional: Include special episodes (Season 0):

jellyfinmanager -find-missing \
  -server "http://localhost:8096" \
  -apikey "your-api-key" \
  -user "username" \
  -tvdb-apikey "your-tvdb-key" \
  -include-specials

Docker Compose

For scheduled backups, you can use docker-compose:

version: '3.8'

services:
  jellyfin-backup:
    image: docker.io/f0rc3/jellyfinmanager
    container_name: jellyfin-backup
    volumes:
      - ./backup:/backup
    environment:
      - JELLYFIN_SERVER=http://jellyfin:8096
      - JELLYFIN_API_KEY=your-api-key
      - JELLYFIN_USER=your-username
    command: ["-backup"]
    # Optionally use a cron container to run this on schedule

For scheduled runs, consider using a cron container or system cron:

# Add to crontab for daily backups at 2 AM
0 2 * * * docker run --rm -v /path/to/backup:/backup -e JELLYFIN_SERVER=... docker.io/f0rc3/jellyfinmanager -backup