Other Settings¶

Smaller configuration areas: external metadata API keys, caching and update checks, logging and debug flags, and deprecated keys.

External API keys¶

All are unset by default and enable optional metadata/geolocation features. For which fields each metadata provider can actually answer with, see What each metadata provider supplies.

Key	Type	Default	Description
`omdb_api_key`	str	`""`	OMDb API key for IMDb metadata lookups; a fallback for when the keyless `imdb` provider has no answer. Free keys are available on the OMDb site.
`tmdb_api_key`	str	`""`	TMDB API key for metadata enrichment and external-ID tags.
`simkl_client_id`	str	`""`	SIMKL client ID for metadata lookups; an alternative/fallback source to TMDB.
`tvdb_api_key`	str	`""`	TheTVDB v4 API key; a fallback source to TMDB, strongest on TV series. Also the source `--enrich --tvdb` reads. Free keys are available on the TVDB site.
`tvdb_pin`	str	`""`	Subscriber PIN, only needed for a user-supported TVDB key. Leave empty for a normal project key.
`tvdb_order`	str	`""`	Default for `--tvdb-order`: renumber episodes to a TVDB season order (`official`, `dvd`, `absolute`, `alternate`, `regional`). Empty keeps the numbering the service gives.
`metadata_providers`	list or map	(see below)	Metadata providers to use, in the order they are tried.
`anilist_title_language`	str	`english`	Which AniList title variant to use: `english`, `romaji`, or `native`.
`disable_metadata`	bool	`false`	Set to `true` to stop all automatic metadata lookups. An ID you give yourself is still looked up.
`decrypt_labs_api_key`	str	`""`	Global Decrypt Labs API key (used by remote CDM / vault).
`ipinfo_api_key`	str	`""`	ipinfo.io API key for IP/region lookups.

How metadata_providers is applied

A lookup goes to each provider in turn and stops at the first good match, so the order decides which source wins. metadata_providers sets that order:

metadata_providers: [tvdb, tmdb, simkl]

Names not in the list are never used, so this both orders and filters. Unknown names are ignored with a warning. Leave it unset for the default order:

metadata_providers: [imdb, omdb, simkl, tmdb, tvdb, anilist]

Whatever the order, unshackle skips a provider that has no API key. imdb and anilist need no key, so they are always available. Available names are imdb, omdb, simkl, tmdb, tvdb, and anilist. The old name imdbapi still works and is read as imdb.

anilist is last in the default order. It only answers for anime and returns nothing for anything else, so it is harmless there. Move it earlier if you mostly download anime.

The order applies to a title search and to a direct lookup of an ID you give with --tmdb, --imdb, --tvdb, or --anilist. A supplied ID always goes to the providers that read that kind of ID, and it never falls back to a title search.

Which AniList title anilist_title_language picks

AniList holds up to three titles for a work: the English one, the romaji transliteration, and the native one. This option says which of them unshackle uses:

anilist_title_language: romaji

A work does not always have all three. When the one you asked for is unset on AniList's side, unshackle falls back in the order english → romaji → native. It takes the first one that is set, so you always get a title.

What disable_metadata turns off

With disable_metadata: true, unshackle never contacts a metadata provider on its own. The title search is dead, and that includes the keyless imdb provider. Titles, years and languages then come only from the service.

disable_metadata: true

An ID you give with --tmdb, --imdb, --tvdb, or --anilist is your permission to use that ID. That lookup still works. unshackle looks the ID up directly, cross references the other IDs from it, and --enrich still reads that source. Only the lookups you did not ask for are stopped.

The imdb provider needs no key

It replaces the earlier imdbapi provider, which read a third-party mirror (api.tiffara.com) and needed the imdb_api_enabled switch. That option is gone: delete it from your config, where it is now ignored.

A different order per title kind

Give a map instead of one list when the best source differs by kind. TVDB is strongest on series, TMDB on films. There are two kinds, tv and movie, and this example sets both of them and names every provider, so nothing is left to the default:

metadata_providers:
  tv: [tvdb, tmdb, simkl, imdb, omdb]
  movie: [tmdb, imdb, omdb, simkl, tvdb]

Each list is independent: it both orders and filters that kind on its own, so a provider you leave out of tv is still used for movie. Here TVDB is tried first for a series and last for a film.

You do not need to give both keys, or a full list in each. A kind you leave out uses the default order:

metadata_providers:
  tv: [tvdb, tmdb]     # movies keep the default order

tv covers every episode and movie covers every film. unshackle only looks up metadata for those two kinds, so any other key, such as anime or music, is ignored.

ipinfo_api_key never touches your service sessions

The token is only ever sent to api.ipinfo.io as a per-request Authorization header; it is never attached to your service session, so it cannot leak to a streaming provider. Lookups degrade gracefully through a fallback chain: the authenticated Lite endpoint (higher rate limits, and ASN/continent data, but no city or region) → anonymous ipinfo → ip-api.in as a last resort.

Caching & updates¶

Title cache¶

unshackle caches fetched title metadata (region- and account-aware) to avoid repeat API calls.

Key	Type	Default	Description
`title_cache_enabled`	bool	`true`	Master switch for the title cache.
`title_cache_time`	int (seconds)	`1800` (30 min)	Lifetime of fresh cached titles.
`title_cache_max_retention`	int (seconds)	`86400` (24 h)	Total retention window for a cached title, counted from when it was cached. Past `title_cache_time` the stale copy is only served as a fallback when a live fetch fails.

Update checks¶

Key	Type	Default	Description
`update_checks`	bool	`true`	Whether to check for new unshackle releases.
`update_check_interval`	int (hours)	`24`	Minimum hours between update checks.

Note

Update checks query the GitHub releases API with a fixed 5-second timeout and cache the result in directories.cache/update_check.json.

Appearance¶

Key	Type	Default	Description
`theme`	str	`catppuccin-mocha`	Named colour theme for all CLI output: banner, logs, progress bars, and help screens. One of `catppuccin-mocha` (aliases `default`, `catppuccin`, `mocha`), `dracula`, `nord`, `gruvbox`, `one-dark` (alias `onedark`), `tokyo-night` (alias `tokyonight`), `monokai`, `flexoki`, `solarized-dark` (alias `solarized`). Case-insensitive; underscores work in place of hyphens. Unknown names fall back to the default with a warning. Preview them all with `unshackle env theme`.

Logging, privacy & debug¶

Key	Type	Default	Description
`redact_paths`	bool	`true`	Mask install-root / venv / home prefixes in logged paths (`<unshackle>`, `<venv>`, `~`). Set `false` to show full paths.
`debug`	bool	`false`	Global debug mode.
`debug_keys`	bool	`false`	Log decryption keys.
`debug_requests`	bool	`false`	Log HTTP requests.
`set_terminal_bg`	bool	`false`	Append the theme's background colour to output styling.

Effect of set_terminal_bg

When on, the theme's background colour is appended to the foreground styles, which makes the full colour palette render correctly on terminals whose default background differs from unshackle's theme. When off, such terminals can render the ASCII-art banner and coloured output incorrectly.

Key exposure

With debug_keys on, decryption content keys are written to the structured debug log at INFO level during the DRM handshake. Treat debug, debug_keys, and the unshackle_debug_*.jsonl files as sensitive, and keep redact_paths enabled when sharing logs.

debug_keys affects only content-encryption keys (the content_key/key fields). Passwords, tokens, cookies, and session tokens are always redacted regardless of this setting, and KIDs, key counts, and other metadata are always logged either way.

Deprecated & removed keys¶

Key	Status	Behaviour
`curl_impersonate`	Deprecated → use `network`	Emits a `DeprecationWarning`; still honoured only if `network` is absent.
`downloader`	Deprecated	Any value other than `"requests"` emits a `DeprecationWarning`; the value is otherwise ignored (the unified requests downloader is always used).
`scene_naming`	Removed	If set to any non-null value, unshackle exits with an error directing you to configure `output_template` instead.
`imdb_api_enabled`	Removed	Ignored. It gated the old `imdbapi` provider, which the keyless `imdb` provider replaces. Safe to delete from your config.