• trakt-sync
  • Intended use
  • Installation
  • Configuration
  • Usage
    • Command Line Flags
    • Command Line Commands
  • API documentation
  • License

Intended use

trakt-sync is a tool for managing and exporting your own Trakt data (history, collection, watchlist, ratings, lists, ...). It must not be used to bulk-collect public data such as other users' lists, comments or ratings, or to feed that data into other services. Paging options (per_page, pages_limit) exist to fetch your own data efficiently, not to crawl the API. Every use has to follow the Trakt API Use Policy.

Installation

go install github.com/mfederowicz/trakt-sync@latest

Configuration

After install, we need API credentials (Client ID and Client Secret). Create a new API app in the Trakt developer portal (a verified GitHub account is required) and save them in config file ($HOME/trakt-sync.toml):

client_id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
token_path = "~/.config/trakt-sync/token.json"
errorCode = 0
warningCode = 0
per_page = 500
pages_limit = 10

Optional defaults for the recommendation filters (the flags of the same name win over them):

ignore_collected = "true"
ignore_watched = "true"
ignore_watchlisted = "true"
watch_window = 30

The three ignore_* values are "true" or "false", quoted or not (ignore_collected = true works too). They are used by recommendations, social_recommendations, smart_lists -a items and users -a activities; watch_window by recommendations and social_recommendations.

Usage

trakt-sync supports a -config flag whose value should correspond to a TOML file. If not provided, trakt-sync will try to use a global config file (assumed to be located at $HOME/trakt-sync.toml). Otherwise, if no configuration TOML file is found then trakt-sync uses a built-in parameters depends on selected module. A value given on the command line (for example -t shows) wins over the same option in the config file (type = "shows"), which wins over the built-in default. One exception: type in the config file is ignored by episodes, lists, movies, people, scrobble, seasons, shows and users. There -t has a module-specific meaning (for example a list type), so give it on the command line.

Command Line Flags

trakt-sync accepts the following command line parameters:

• -config [PATH] - path to config file in TOML format, defaults to $HOME/trakt-sync.toml if present.
• -version - get trakt-sync version.

Command Line Commands

trakt-sync accepts the following command line commands/modules:

• calendars - By default, the calendar will return all shows or movies for the specified time period and can be global or user specific.
• certifications - Certifications list
• checkin - Checkin movie,episode,show_episode,delete
• comments - Comments comments,comment,replies,item,likes,like,trending,recent,updates,reactions,reactions_summary,reaction,report.
• collection - Get all collected items in a user's collection.
• countries - Get a list of all countries, including names and codes.
• episodes - Returns data about episodes: summary, season, episodes, translations, comments etc...
• genres - Get a list of all genres, including names and slugs.
• help - Help on the trakt-sync command and subcommands.
• history - Returns movies and episodes that a user has watched, sorted by most recent.
• languages - Get a list of all laguages, including names and codes.
• lists - Returns data about lists: trending, popular, list, likes, like, items, comments, report.
• media - Returns movies and shows together: trending, popular, anticipated.
• movies - Returns data about movies: trending, popular, list, likes, like, items, comments etc...
• networks - Get a list of all TV networks
• notes - Manage notes created by user
• people - Returns all data for selected person.
• recommendations - Recommendations manage movie and shows recommendations for user
• scrobble - Scrobble for start/pause/stop movie,show,episode
• search - Searches can use queries or ID lookups.
• seasons - Returns data about seasons: summary, season, episodes, translations, comments etc...
• shows - Returns data about movies: trending, popular, list, likes, like, items, comments etc...
• smart_lists - Returns a smart list definition, the items it resolves to or the official templates.
• social_recommendations - Deprecated since 2026-10-13 (Trakt dropped the endpoints from its API contract): movie and show recommendations based on the people you follow.
• sync - Sync data useful for mediacenters: activities, playbacks, collections, ratings, watchlists, favorites.
• team - Returns Trakt team members.
• users - Returns all data for a user.
• watchlist - Returns all items in a user's watchlist filtered by type.
• watchnow - Returns watch now sources (streaming providers), all or by country.
• younify - Streaming service connections: connections, connect, refresh, disconnect.

Library usage

The API client behind the CLI is also a Go package, github.com/mfederowicz/trakt-sync/trakt. It is experimental: its API may still change in minor releases, listed in the changelog with a Library: prefix. See the versioning rules at the top of CHANGELOG.md.

go get github.com/mfederowicz/trakt-sync/trakt

client := trakt.NewClient(nil).
	WithClientID(os.Getenv("TRAKT_CLIENT_ID")).
	WithUserAgent("my-app/1.0")

movies, _, err := client.Movies.GetTrendingMovies(context.Background(), &uri.ListOptions{Limit: 10})

Package docs: pkg.go.dev/github.com/mfederowicz/trakt-sync/trakt. Runnable programs (device login, trending, paginated history, errors) are in example/. The Trakt API Use Policy applies to every app built on it.

API documentation

• Trakt developer portal - official guides (authentication, pagination, rate limiting, required headers) and management of your API apps.
• trakt/trakt-api - API contract used as the source of truth for this project; API announcements are published there.
• API coverage - which Trakt API routes trakt-sync implements, and what is still missing.

License

MIT