imdb-trakt-sync

Command line application that can sync IMDb and Trakt user data - watchlist, lists, ratings and history.
To achieve its goals the application is using the Trakt API and web scraping.
Keep in mind that this application is performing one-way sync from IMDb to Trakt. This means that any changes made on IMDb will be reflected on Trakt, but not the other way around.

Configuration

FIELD NAME	FIELD TYPE	DEFAULT VALUE	ALLOWED VALUES	DESCRIPTION
IMDB_AUTH	variable	cookies	credentials cookies none	Authentication method to be used for IMDb: credentials => IMDB_EMAIL + IMDB_PASSWORD fields required cookies => IMDB_COOKIEATMAIN field required none => IMDB_LISTS field required
IMDB_EMAIL	secret	-	-	IMDb account email address. Only required when IMDB_AUTH => credentials
IMDB_PASSWORD	secret	-	-	IMDb account password. Only required when IMDB_AUTH => credentials
IMDB_COOKIEATMAIN	secret	-	-	Cookie value only required when IMDB_AUTH => cookies. Get the following cookie information from your browser: name: at-main | domain: .imdb.com
IMDB_LISTS	variable	-	-	Array of IMDb list IDs that you would like synced to Trakt. If this array is not specified or empty, all IMDb lists on your account will be synced to Trakt. In order to get the ID of an IMDb list, open it from a browser - the ID is in the URL with format ls#########. If provided as GitHub secret or environment variable, define its values as comma-separated list. Keep in mind the Trakt list limits!
IMDB_IGNOREDLISTS	variable	-	-	Array of IMDb list IDs that you do NOT want synced to Trakt. This is useful if you would like to sync all your lists, but ignore some. In order to get the ID of an IMDb list, open it from a browser - the ID is in the URL with format ls#########. If provided as GitHub secret or environment variable, define its values as comma-separated list.
IMDB_TRACE	variable	false	true false	Print tracing logs related to browser activities. Can be useful for debugging purposes
IMDB_HEADLESS	variable	true	true false	Whether to run the browser in headless mode or not. Only set this to false when running the syncer locally
IMDB_BROWSERPATH	variable	-	-	The location of your preferred web browser. If you leave this value empty, the syncer will attempt to lookup common browser locations. You can optionally override its value to use a specific browser
SYNC_MODE	variable	dry-run	full add-only dry-run	Sync mode to be used when running the application: full => add Trakt items that don't exist, delete Trakt items that don't exist on IMDb, update Trakt items by treating IMDb as the source of truth add-only => add Trakt items that do not exist, but do not delete anything dry-run => identify what Trakt items would be added / deleted / updated
SYNC_HISTORY	variable	false	true false	Whether to sync history or not. When IMDB_AUTH => none, history sync will be skipped
SYNC_RATINGS	variable	true	true false	Whether to sync ratings or not. When IMDB_AUTH => none, ratings sync will be skipped
SYNC_WATCHLIST	variable	true	true false	Whether to sync watchlist or not. When IMDB_AUTH => none, watchlist sync will be skipped
SYNC_LISTS	variable	true	true false	Whether to sync lists or not. This provides the option to disable syncing of lists
SYNC_TIMEOUT	variable	15m	-	Maximum duration to run the syncer. Users with large libraries might have to increase the timeout value accordingly. Valid time units are: ns, us (or µs), ms, s, m, h
TRAKT_CLIENTID	secret	-	-	Trakt app client ID
TRAKT_CLIENTSECRET	secret	-	-	Trakt app client secret
TRAKT_TOKENFILE	variable	trakt-token.json	-	Path to the file used to store the Trakt access/refresh tokens. Created automatically the first time the application authorizes with Trakt (see Usage) and kept up to date automatically afterwards

Trakt no longer supports signing in with an email and password from third-party applications - the application authorizes using Trakt's device code flow instead. The first time the application runs without an existing token file, it prints a verification URL and a code.

Open the URL in any browser, sign in however you normally would (Google, Apple, or an email sign-in link), and enter the code. The application polls in the background and, once approved, saves the resulting tokens to TRAKT_TOKENFILE so subsequent runs don't need to repeat this manual step. Once the access token expires, the refresh token will be used to generate a fresh pair of auth tokens.

Usage

The application can be setup to run automatically, based on a custom schedule (default: once every 12 hours) using GitHub Actions, in a container, or locally on your machine.
Workflow schedules can be tweaked by editing the .github/workflows/sync.yaml file and committing the changes.
Please configure the application to suits your needs, by referring to the Configuration section, before running it.
Follow the relevant section below, based on how you want to use the application.

Run the application using GitHub Actions

1. Fork the repository to your account
2. Create a Trakt App. Use urn:ietf:wg:oauth:2.0:oob as redirect uri
3. Configure the application in your fork (see Configuration):
   • Create an individual repository secret/variable for each Configuration field you need: Settings > Secrets and variables > Actions
   • Create a GH_PAT repository secret (see Creating the GH_PAT secret)
4. Allow GitHub Actions on your fork repository: Settings > Actions > General > Allow all actions and reusable workflows
5. Enable the sync workflow: Actions > Workflows > sync > Enable workflow
6. Run the sync workflow manually: Actions > Workflows > sync > Run workflow
7. From now on, GitHub Actions will automatically trigger the sync workflow based on your schedule

Creating the GH_PAT secret

The sync workflow needs to overwrite the TRAKT_TOKEN repository secret any time new pair of Trakt auth tokens are generated. The default GITHUB_TOKEN that Actions provides automatically cannot modify repository secrets, so a personal access token (PAT) with that specific permission is needed instead. A fine-grained token scoped to just this repository and just this permission is recommended over a classic token:

1. Go to Fine-grained tokens
2. Give your token a name (e.g. imdb-trakt-sync) and an expiration
3. Under Repository access choose Only select repositories and pick your imdb-trakt-sync fork
4. Click Add permissions and select Secrets with Read and write access
5. Click Generate token and ensure you copy its value
6. Create a new repository secret called GH_PAT in your fork and set its value to the copied token

Run the application in a Docker container

1. Install Docker
2. Clone the repository: git clone git@github.com:cecobask/imdb-trakt-sync.git
3. Create a Trakt App. Use urn:ietf:wg:oauth:2.0:oob as redirect uri
4. Configure the application:
   • Create .env file with the same contents as .env.example
   • Populate the .env file with your own secret values
   • All secret keys should have ITS_ prefix
5. Open a terminal window in the repository folder and then:
   • Build a Docker image: make package
   • Run the sync workflow in a Docker container: make sync-container
   • The first run prints a Trakt verification URL and code - open it in a browser and approve it (see Configuration). The resulting token is persisted to trakt-token.json on the host via a mounted volume, so later runs of make sync-container reuse it without prompting again

Run the application locally

1. Install Git and Go
2. Clone the repository: git clone git@github.com:cecobask/imdb-trakt-sync.git
3. Create a Trakt App. Use urn:ietf:wg:oauth:2.0:oob as redirect uri
4. Open a terminal window in the repository folder and then:
   • Build the syncer: make build
   • Configure the syncer: make configure
   • Run the syncer: make sync
   • The first run prints a Trakt verification URL and code - open it in a browser and approve it (see Configuration). The resulting token is saved to trakt-token.json, so later runs reuse it without prompting again