unshackle/docs/reference/configuration/misc.md

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 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.

!!! note "How metadata_providers is applied" A lookup goes to each metadata provider in turn and stops at the first good match, so the order decides which source wins. metadata_providers sets that order:

```yaml
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:

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

Whatever the order, unshackle skips a metadata provider that has no API key. `imdb` and
`anilist` need no API 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.

!!! note "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:

```yaml
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.

!!! note "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 metadata provider. Titles, years and languages then come only from the service.

```yaml
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. unshackle stops only the lookups you
did not ask for.

!!! note "The imdb provider needs no key" It replaces the earlier imdbapi metadata 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.

!!! tip "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 metadata provider, so nothing is left to the default:

```yaml
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 unshackle
still uses for `movie` a metadata provider you leave out of `tv`. Here unshackle tries TVDB
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:

```yaml
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 unshackle ignores any other config key, such as `anime` or `music`.

!!! note "ipinfo_api_key never touches your service sessions" unshackle sends the token only to api.ipinfo.io, as a per-request Authorization header. It never goes on your service HTTP session, so it cannot leak to a streaming service. 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.

!!! note "Effect of set_terminal_bg" When on, unshackle appends the theme's background colour 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.

!!! danger "Key exposure" With debug_keys on, unshackle writes the content keys 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, content 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.