Skip to content

Modules

chodeus edited this page Oct 22, 2026 · 32 revisions

🏠 Home › Modules

Modules

CHUB ships fourteen core modules. Each is a chore you can schedule or run on demand, with its own section in config.yml and its own page under Settings → Modules.

🧩 full image extensions. cl2k_maker and poster_self_heal ship only in the full image (ghcr.io/chodeus/chub:full, or vX.Y.Z-full). On latest they are switched off: no config section, no settings page. See Installation → Image tags.

Settings → Modules lists every module with an on/off switch (general.disabled_modules). A module that is off is skipped by the scheduler, can't be run by hand, and its webhook jobs are skipped. Click a module for its settings page, with Dry run, Run now and Save in the header.

Each Config block below shows the default values unless a comment says otherwise; paths and instance names are examples.

On this page: What every module supports · Module summary · then one section per module:

  • 🖼️ poster_renamerr — rename posters to match your library
  • 🪧 asset_renamerr — apply logos, square art, and backgrounds
  • 🎨 border_replacerr — apply brand or holiday borders
  • 🎬 cl2k_maker — generate CL2K-style posters · 🧩 full image
  • 🩹 poster_self_heal — keep generated CL2K posters' ids/titles current · 🧩 full image
  • 🧹 poster_cleanarr — sweep Plex Metadata bloat, orphan assets, and stale-duplicate asset folders
  • 🏷️ labelarr — mirror ARR tags into Plex labels
  • 🔍 jduparr — hardlink duplicate media files
  • 🔗 nohl — find and replace non-hardlinked media
  • ❓ unmatched_assets — report media without posters
  • ⬆️ upgradinatorr — trigger ARR upgrade searches
  • ✏️ renameinatorr — apply ARR naming to existing files
  • 🩺 health_checkarr — remove ARR items that TMDB/TVDB no longer list
  • 🪺 nestarr — report ARR↔Plex mismatches, nested folders, and stray or missing files
  • ☁️ sync_gdrive — pull poster assets from Google Drive
  • 🧼 plex_maintenance — Plex cleanup (trash, bundles, DB, photo cache)

What every module supports

  • Dry run — dry_run: true (or the Dry run switch on the module page) logs what the module would do without changing anything. Use it the first time. unmatched_assets and nestarr are report-only and have none.
  • Log level — debug (each item's decision) or info (default).
  • Cancel — click the module's Running button in the Dashboard's Modules table. Most modules stop at the next item; see the summary for the exceptions.
  • Run history — Settings → Jobs lists each run with its status and trigger; the full log is on Logs.
  • Several schedules — Settings → Schedule can give a module extra schedule blocks, each with its own settings (for example poster_cleanarr reporting daily and removing weekly). See Configuration → schedule.

Module summary

Poster & artwork

Module What it does Cancellable Report-only
poster_renamerr Match posters to your library and rename/apply them Yes No
asset_renamerr Apply logos, backgrounds, and square art Yes No
border_replacerr Apply brand or holiday borders No No
poster_cleanarr Sweep Plex Metadata bloat, orphan assets, and stale-duplicate asset folders Yes No (has report mode)
sync_gdrive Pull poster assets from Google Drive Yes No
unmatched_assets Report media missing a poster Yes Yes

Media library

Module What it does Cancellable Report-only
labelarr Mirror ARR tags into Plex labels Yes No
jduparr Hardlink duplicate media files with jdupes After the current scan No
nohl Find non-hardlinked media and replace it through the ARR Yes No (has scan mode)
upgradinatorr Trigger ARR upgrade searches Yes No
renameinatorr Apply ARR naming to existing files Yes No
health_checkarr Delete items removed from TMDB/TVDB Yes No
nestarr Report ARR↔Plex mismatches, nested folders, stray and missing files Yes Yes

Maintenance

Module What it does Cancellable Report-only
plex_maintenance Plex housekeeping (trash, bundles, DB, photo cache) Partial No

🧩 full image extensions

Module What it does Run model Report-only
cl2k_maker Generate CL2K-style posters from TMDB/fanart art On demand from Assets → CL2K Poster Maker; no scheduled run No
poster_self_heal Keep generated CL2K posters' embedded ids/titles/years canonical Scheduled / on demand Detect-only by default (opt-in auto_apply)

🖼️ poster_renamerr

Matches poster files against your Radarr/Sonarr/Lidarr libraries, renames them, and either writes them into a Kometa asset folder or uploads them straight to Plex.

Settings page: Inputs (source directories, instances & Plex, music art when a Lidarr instance exists) and Output & pipeline (apply method, chained actions, logging).

Setup

  1. Set apply_method: kometa (write renamed files to destination_dir) or plex (upload to Plex).
  2. List your own poster folders in source_dirs (drag to reorder). Bottom of the list wins when two sources have a poster for the same item.
  3. List instances (Radarr/Sonarr/Lidarr) — they supply the media list.
  4. Pick Plex libraries under Plex Libraries (plex_scope). For the plex method, turn on Upload posters to this Plex instance. Match collections in selected libraries matches collection posters (no libraries picked = all enabled libraries).
  5. Optionally chain run_border_replacerr, run_asset_renamerr, clean_orphan_assets and report_unmatched_assets.

Every Sync GDrive drive is a source automatically, unless it's set to Browse only. Drives you don't list in source_dirs are added after it, so they outrank your own folders; list a drive there to set its priority yourself.

Skip unchanged posters (skip_unchanged_uploads, on by default) skips any poster whose source file hasn't changed since it was applied (Plex method). After adding a Plex library or changing border settings, turn it off for one run so existing posters are applied again.

How matching works. CHUB matches against the metadata your *arr holds (title, year, TVDb/TMDb/IMDb id, season), read from its API — not from your media folder names. An id in the poster filename gives the most reliable match; otherwise it uses the title, year and season from the filename. So name your library however you like, and improve matching through the poster files' names and id tags.

Nothing moving? See Troubleshooting. End-to-end Kometa setup: Kometa Integration.

Config

poster_renamerr:
  dry_run: false
  log_level: info
  apply_method: kometa                  # kometa | plex (legacy "direct" = plex)
  action_type: copy                     # copy | move | hardlink | symlink (kometa)
  asset_folders: false                  # true = <Show>/poster.jpg, Season01.jpg; false = <Show>_Season01.jpg (kometa)
  sync_posters: false                   # run sync_gdrive before each run
  print_only_renames: false             # log only newly renamed files
  run_border_replacerr: false
  run_asset_renamerr: false
  clean_orphan_assets: false            # action follows poster_cleanarr.orphan_assets_mode
  report_unmatched_assets: false
  upload_delay_ms: 0                    # pause after each Plex upload, 0–5000; try 50 if Plex struggles
  skip_unchanged_uploads: true          # plex method
  source_dirs: [/posters/custom]
  destination_dir: /kometa              # kometa: Kometa's asset_directory
  # Music art (Lidarr):
  music_source_dirs: []                 # custom artist posters / album covers
  music_lock_artist_art: false          # plex: lock artist art so Plex's music agent can't replace it
  music_lma_sidecars: false             # also write cover.jpg / artist-poster.jpg / background.jpg into music folders
  instances: [radarr_main, sonarr_main] # Radarr / Sonarr / Lidarr names
  plex_scope:
    - instance: plex_main
      library_names: ["Movies", "TV Shows"]   # empty = all enabled libraries
      add_posters: true                 # default false; plex method: upload here
      match_collections: true           # default false

🪧 asset_renamerr

Applies logo, square art, and background artwork to matched media, using poster_renamerr's matching. Unchanged assets (same file, same fanart.tv URL) are skipped.

Settings page: Inputs (asset types, source) and Output & pipeline (apply, instances & Plex, logging).

Setup

  1. Pick the Primary Source: local files first (fanart.tv fills gaps) or fanart first (local files fill gaps).
  2. For fanart.tv, add your free personal API key under Settings → General → fanart.tv. Without it, fanart.tv is skipped. It supplies logos and backgrounds only; square art always comes from local files.
  3. Pick asset_types, apply_method and action_type, then instances (Radarr/Sonarr) and plex_scope as for poster_renamerr.
  4. Run it chained (poster_renamerr.run_asset_renamerr: true, which reuses that run's sync, scan and Plex data) or on its own.

Local file naming: as for posters — Title (Year) {tmdb-123} — plus a type tag after - or _: - Logo.png, - Background.png, - SquareArt.png (Kometa's _square works too). No tag = a poster. Case-insensitive.

What applies where:

Level logo background squareart
Movie / Show / Collection ✅ plex · ✅ kometa ✅ plex · ✅ kometa ✅ plex · ✅ kometa (Kometa 2.4.5+)
Season — ✅ plex · ✅ kometa (Season##_background) ✅ plex only
Album — ✅ plex · ✅ kometa (<Album>_background) ✅ plex · ✅ kometa

No provider publishes season logos, so CHUB never looks for them. Kometa doesn't read season square art, hence Plex-only. Banners are recognised but never applied — neither Plex nor Kometa can take one.

Gotcha: on the plex method, art goes to every library the item lives in (e.g. both 1080p and 4K). On kometa, asset_folders must match Kometa's and poster_renamerr's — Kometa has one global toggle, so a mismatch leaves half the tree unread. CHUB warns when the modules disagree.

Config

asset_renamerr:
  dry_run: false
  log_level: info
  print_only_renames: false             # log only newly applied assets
  sources: [local, fanart]              # first = preferred, second = fallback
  asset_types: [logo, background, squareart]
  apply_method: kometa                  # kometa | plex (legacy "direct" = plex)
  action_type: copy                     # copy | move | hardlink | symlink (kometa)
  asset_folders: false                  # match poster_renamerr and Kometa
  destination_dir: /kometa              # kometa: Kometa's asset_directory
  source_dirs: [/posters/custom]
  music_source_dirs: []                 # YAML only: music art (Lidarr)
  sync_assets: false                    # run sync_gdrive first (standalone runs)
  tmdb_language: [en]                   # fanart.tv languages in priority order; textless art is always a fallback
  instances: [radarr_main, sonarr_main] # Radarr / Sonarr names
  plex_scope:
    - instance: plex_main
      library_names: ["Movies", "TV Shows"]
      add_posters: true                 # default false; plex method: upload here

🎨 border_replacerr

Re-applies a brand or holiday border to matched posters. Not cancellable — restart the container to stop a big run.

  • Color mode — crops border_width px off each edge and paints a flat border, cycling through border_colors (or the active holiday's colors).
  • Image mode — when the active holiday has borders:, composites a 1000×1500 decorative PNG over the poster; border_width is ignored.
  • Remove mode — no border_colors and no active holiday: the border is cropped off and not replaced.

The crop assumes the TPDB convention of a 26 px white border; art without one loses border_width px of real content per edge. If two holidays overlap, the first listed wins.

Where settings live: Settings → Modules → Border Replacerr has the paths, border_width, default colors, filters and the holiday list (name + date window; a preset fills both). Assets → Border Replacerr has the default and per-holiday colors, border art, and a live preview.

Run from poster_renamerr (run_border_replacerr), it processes only that run's posters and ignores source_dirs / destination_dir.

Bundled themed borders

56 SVG borders across 13 holidays, each a decorative ring with a transparent center.

Holiday Variants Schedule (default preset)
🎆 New Year's Day v1 – v4 12/30 – 01/02
🧧 Lunar New Year v1 – v4 01/20 – 02/20
💘 Valentine's Day v1 – v5 02/05 – 02/15
🍀 St. Patrick's Day v1 – v4 03/14 – 03/18
🐣 Easter v1 – v4 03/31 – 04/02
🌸 Mother's Day v1 – v4 05/10 – 05/15
👨‍👧‍👦 Father's Day v1 – v4 06/15 – 06/20
🏳️‍🌈 Pride v1 – v5 06/01 – 06/30
🗽 Independence Day v1 – v4 07/01 – 07/05
🧹 Labor Day v1 – v4 09/01 – 09/07
🎃 Halloween v1 – v5 10/01 – 10/31
🦃 Thanksgiving v1 – v4 11/01 – 11/30
🎄 Christmas v1 – v5 12/01 – 12/31

Christmas v1 Halloween v1 Valentine's v1 Pride v1

Browse the full set in backend/assets/borders/.

Custom borders

Drop PNGs into /config/borders/<holiday-folder>/. A file wins over a bundled one with the same name.

Requirement Value
Size 1000 × 1500 (2:3); other sizes are resized, losing quality
Format PNG with an alpha channel
Transparent center (60, 60) to (940, 1440) — the poster shows through
Outer ring The 60 px band at the edges, opaque; corner ornaments may reach ~120 px in
Content No text, faces, or copyrighted IP — it appears on every poster

Folder names: newyear, lunarnewyear, valentines, stpatricks, easter, mothersday, fathersday, pride, independence, labor, halloween, thanksgiving, christmas. A custom holiday's folder is its name in lowercase letters and digits only.

To use one, save it as /config/borders/<holiday-folder>/<name>.png, then on Assets → Border Replacerr expand the holiday, click it in the Custom row, and save. The borders: list is the rotation order; names are case-sensitive and the .png is optional. A name that matches no file is skipped with a warning.

Config

border_replacerr:
  dry_run: false
  log_level: info
  source_dirs: [/posters]               # standalone runs only
  destination_dir: /posters             # standalone runs only
  border_width: 26                      # 0–200, color mode
  border_workers: null                  # re-encode threads; null = min(8, CPU cores)
  border_colors: ["#ff7300"]            # default []; empty = remove the border
  ignore_folders: []                    # source folder names to skip
  exclusion_list: null                  # media titles to leave alone
  holidays:
    - name: 🎃 Halloween                # color mode
      schedule: "range(10/01-10/31)"
      colors: ["#FF6600", "#000000"]
    - name: 🎄 Christmas                # image mode — borders win over colors
      schedule: "range(12/01-12/26)"
      colors: ["#C8102E", "#00843D"]    # used if a border file is missing
      borders: [v1, v2, v3, custom-roses]   # custom-roses = /config/borders/christmas/custom-roses.png

🎬 cl2k_maker

🧩 full image only.

Generates CL2K-style posters (contain-fit backdrop, black-fill bottom, template gradient, logo or typeset wordmark) from TMDB/fanart.tv art, plus matching logo, background and square-art images.

CL2K Maker walkthrough — click to play

▶ Watch the walkthrough (Streamable).

Run model: config-only. There's no scheduled run and no Run now; it isn't listed on the Schedule or Notifications pages. Generate on demand from Assets → CL2K Poster Maker: search a title (movie, show, collection, or a batch of seasons), pick art, frame the backdrop, preview, and save. The page also exports .psd.

Setup

  1. Add local folders (local_folders): a name, a path, and the image types it takes (poster, logo, background, squareart). Every folder that claims a type gets a copy. Add the poster folder to poster_renamerr.source_dirs so generated posters get applied.
  2. Optionally add Drive uploads (gdrive_uploads) the same way, with a Drive folder_id. They use the Sync GDrive OAuth token (a service account can't own files in a personal Drive).
  3. Tune whiten_logo, text_logo_fallback and text_logo_stroke.

A type no location claims isn't saved, but you can still download it from the page. An older output_dir / upload_to_gdrive / gdrive_folder_id config is converted on load.

Drive-only saves aren't cached, so poster_renamerr won't apply them. poster_self_heal still covers them.

Config

cl2k_maker:
  log_level: info
  language: en                          # preferred logo/backdrop language
  whiten_logo: true                     # recolor dark logos white
  text_logo_fallback: true              # typeset a wordmark when there's no logo
  text_logo_stroke: 0                   # wordmark outline, 0–20 px
  skip_existing: true                   # don't regenerate an existing CL2K poster
  style: CL2K                           # poster_cache style tag
  priority: 0
  local_folders:                        # default []
    - name: Posters
      path: /posters/cl2k
      types: [poster]
  gdrive_uploads:                       # default []
    - name: My Drive
      folder_id: "<google-drive-folder-id>"
      types: [poster, logo]
  # Optional AI text removal (needs a brushed mask, except openai, which can use the prompt alone):
  ai_provider: none                     # none | lama_sidecar | openai
  ai_endpoint: ""                       # lama sidecar URL
  api_key: ""                           # openai token
  client_key: ""                        # lama sidecar key (sent as X-API-Key)
  ai_model: ""                          # openai model (default gpt-image-1)
  ai_timeout: 300
  ai_mask_dilate: -1                    # lama mask dilation; -1 = the sidecar's default
  ai_logo_upscale: true                 # upscale a too-small logo before falling back to the wordmark
  ai_prompt: "Remove all text, titles, credits, logos and watermarks…"

API: /api/cl2k-maker/* (search, resolve, images, details, preview, generate, square-generate, background-generate, logo-asset-generate, generate-seasons, generated, psd-export, test-drive, …).


🩹 poster_self_heal

🧩 full image only. Needs cl2k_maker and a TMDB key.

Keeps the ids, title and year in your generated CL2K poster filenames current. When a show gets a new TVDB id or a title or year changes, the filename drifts and stops matching. The healer finds the poster's live library item (by id, then title + year), asks TMDB for the canonical title and year, and rebuilds the filename. If it differs, that's a proposal. Season formatting alone (Season 1 vs Season 01, Specials vs Season 0) is never a proposal.

What it heals: posters in the CL2K maker's local_folders (your own output, not synced-in drives that share the style tag), and a live listing of its gdrive_uploads folders — the source of truth for a Drive-only setup (needs the Sync GDrive OAuth token). With neither set, there's nothing to heal.

Run model: scheduled or on demand, detect-only by default. Proposals wait on Assets → Poster Healer Review (/poster/heal-review; the CL2K Poster Maker page links to it) to be applied or dismissed. With auto_apply, confident fixes are renamed during the run; a title that matches more than one item always waits for you. Applying renames the Drive copy first, then the local copy if there is one.

Config

poster_self_heal:
  log_level: info
  backfill_ids: true     # also add ids to posters that have none
  auto_apply: false      # rename confident fixes during the run

API: /api/poster-self-heal/* (reviews, count, coverage, reviews/{id}/apply, reviews/{id}/dismiss).


🧹 poster_cleanarr

Three cleanup passes in one module. Each run does the bloat pass in its mode, plus the orphan and stale passes when they're switched on. All default to report.

Settings page: Plex metadata (Plex connection, bloat pass) and Asset folders (asset sources, orphan assets, stale duplicates). Each pass card has its own action row; the orphan and stale cards have an on/off switch.

Pass What it finds Switch / mode move goes to
Bloat Poster variants in Plex's Metadata/ that Plex no longer uses mode: report · move · remove · restore (move back) · clear (empty the restore folder) · nothing <plex_path>/Poster Cleanarr Restore/
Orphan Files in asset_dirs with no parent media in the orphan_instances libraries orphan_assets_enabled + orphan_assets_mode: report · move · remove .chub_orphan_restore/ in each asset dir
Stale duplicates Kometa asset folders whose {tmdb-N}/{tvdb-N} matches a live item but whose name is outdated (e.g. after a folder rename) stale_duplicates_enabled + stale_duplicates_mode: report · move · remove same as orphan

Promote each pass report → move → remove after checking a run.

  • Bloat uses the first Plex instance in instances. Artwork Plex still uses is protected server-wide, collection and people artwork is never bloat, and Plex's live database is re-checked before a delete. excluded_libraries skips whole libraries (handy for Music, whose album art otherwise shows as (unknown)); it can only reduce what's deleted. overlays_only: true skips files without Kometa's overlay EXIF tag, sparing your own uploads.
  • Orphan keeps a file if its id tag or its title matches. CHUB re-syncs the orphan_instances first and skips the pass if that fails. include_collections keeps collection posters; orphan_ignore_titles exempts titles.
  • Stale always keeps the folder that matches the media, and never moves or removes a duplicate while that folder isn't on disk yet.

Instances: instances is Plex only. orphan_instances is the Radarr/Sonarr libraries that define which assets are legitimate; empty = fall back to instances (older configs that mixed both are split automatically).

Gotcha: plex_path is the container path of the Plex Media Server data folder — the one containing Metadata/, Cache/ and Plug-in Support/. Mount the host's Library/Application Support/Plex Media Server/ at, say, /plex and enter /plex, not /plex/Metadata.

Not unmatched_assets. That reports media missing a poster; orphan cleanup acts on posters missing their media.

Assets → Poster Cleanarr shows bloat per title, stale-duplicate counts, and an orphan list where you can delete an orphan directly.

Config

poster_cleanarr:
  log_level: info
  mode: report                          # bloat pass
  plex_path: /plex                      # Plex Media Server data folder
  excluded_libraries: []                # Plex libraries the bloat pass skips
  overlays_only: false
  local_db: false                       # copy the Plex DB from disk instead of via the API (Plex must be stopped)
  use_existing_db: false                # reuse a DB copy under 2 hours old
  ignore_running: false                 # local_db: skip the "is Plex running" check
  sleep: 60                             # seconds between operations
  timeout: 600                          # Plex connection timeout (seconds)
  instances: [plex_main]                # Plex only
  orphan_assets_enabled: false
  orphan_assets_mode: report
  orphan_instances: [radarr_main, sonarr_main]   # default []
  orphan_ignore_titles: []
  asset_dirs: [/kometa]                 # default []; walked recursively
  include_collections: true
  stale_duplicates_enabled: false
  stale_duplicates_mode: report

🏷️ labelarr

Mirrors Radarr/Sonarr tags into Plex labels — tag an item favorite in Sonarr and it gets the favorite label in the mapped Plex library. Removing the tag removes the label on the next run.

Setup: add a mapping per ARR instance — app_instance, labels (the tags to mirror; a list or a comma-separated string), and plex_instances with their libraries. Untick Enabled to pause a mapping.

Library → Label Sync (/media/labelarr) shows each mapping's status and last sync, edits mappings inline, and has Sync now.

Config

labelarr:
  dry_run: false
  log_level: info
  mappings:
    - app_instance: sonarr_main
      enabled: true
      labels: [watched, favorite]
      plex_instances:
        - instance: plex_main
          library_names: ["TV Shows"]

🔍 jduparr

Runs jdupes over your media trees (video files only), finds identical files, and hardlinks them together so they use disk space once. The log reports how many files were relinked. dry_run lists the duplicate groups without linking.

Setup: point source_dirs at your media trees — duplicates are found across all of them, so they must share one filesystem. Optionally set hash_database so later runs reuse the hashes.

Gotcha: the first run on a large library takes hours. hash_database can't contain a null byte or start with -, and its parent folder must exist.

Config

jduparr:
  dry_run: false
  log_level: info
  hash_database: /config/jduparr.db     # default none
  source_dirs: [/media/movies, /media/tv]

🔗 nohl

Finds media files with no hardlink — usually a copy instead of a hardlinked import, taking disk space twice — and replaces them through the ARR.

resolve mode (default) deletes the file through Radarr/Sonarr, waits for the ARR's refresh, then searches (a season search for Sonarr) so the ARR imports a new, hardlinked copy. The search runs even if the refresh times out. Start with dry_run: true. scan mode only reports.

Setup: list source_dirs with a mode each, set searches (per run; each Sonarr season counts as one) and any exclude_* lists, and list the Radarr/Sonarr instances.

Config

nohl:
  dry_run: false
  log_level: info
  searches: 10
  print_files: false                    # log every non-hardlinked file
  source_dirs:
    - { path: /media/movies, mode: resolve }   # scan | resolve
    - { path: /media/tv,     mode: resolve }
  exclude_profiles: []                  # quality profile names
  exclude_movies: []
  exclude_series: []
  instances: [radarr_main, sonarr_main]

❓ unmatched_assets

Reports library items with no matching poster. Changes nothing.

Setup: list instances (Radarr/Sonarr/Lidarr). To also report Plex collections without a poster, pick libraries under plex_scope (no libraries = all enabled ones). Tune the ignore_* filters. Run it on its own or from poster_renamerr (report_unmatched_assets).

Flagged when an item has no matched poster, passes your filters, and is released or already has a file (announced / TBA / upcoming items with nothing on disk are skipped). ignore_unmonitored respects per-season monitoring.

Where to act: Assets → Unmatched Assets (/poster/unmatched) to ignore an item or a season, pick a poster, or approve a match — see UI Guide. Assets → Statistics has a Request button per row that copies a Discord-ready request (title, TMDb link, and for series the missing seasons).

Config

unmatched_assets:
  log_level: info
  ignore_folders: []
  ignore_profiles: []                   # quality profiles
  ignore_titles: []
  ignore_tags: []                       # ARR tags
  ignore_collections: []                # Plex collections
  ignore_unmonitored: false
  instances: [radarr_main, sonarr_main]
  plex_scope:                           # default []; report collections without a poster
    - instance: plex_main
      library_names: ["Movies"]

⬆️ upgradinatorr

Each run picks a set number of not-yet-searched items per ARR instance, searches them, and tags them, so every item gets a turn. Lidarr is fully supported. The run summary lists what was actually upgraded or downloaded (from the ARR's history), not just what was grabbed.

Profiles (instances_list) — one or more per instance:

  • count and search_mode: upgrade (every untagged item), missing (no file), or cutoff (below the quality cutoff).
  • An optional label, an enabled switch, and an optional own schedule (without one, the profile runs with the main Upgradinatorr schedule or Run now).
  • tag_name (blank = checked) marks searched items; ignore_tag (blank = ignore) excludes items. unattended: true clears the tags and starts over once every item is tagged.
  • queue_block_hours (default 72) skips an item that already has a download waiting to import, until that download is older than this — so a second copy isn't grabbed. 0 = off.
  • Sonarr: season_monitored_threshold is a percentage (0–100); a season with fewer monitored episodes is not searched.

count_mode (Sonarr and Lidarr):

Mode count caps Tagging
series_artist (default) Series / artists per run (every monitored season/album searched) After one pass
season_album Season / album searches per run — gentler on trackers When all children are searched; progress resumes next run

Switching modes is safe.

Config

upgradinatorr:
  dry_run: false
  log_level: info
  instances_list:
    - label: Movies upgrades
      enabled: true
      instance: radarr_main
      count: 10
      tag_name: checked
      ignore_tag: ignore
      unattended: false
      search_mode: upgrade              # upgrade | missing | cutoff
      queue_block_hours: 72
    - instance: sonarr_main
      schedule: "daily(03:00)"          # empty = runs with the main schedule
      count: 5
      count_mode: season_album          # series_artist | season_album
      season_monitored_threshold: 50    # percent of a season's episodes monitored
      search_mode: upgrade

✏️ renameinatorr

Applies each ARR's own naming scheme to existing files and folders in Radarr, Sonarr and Lidarr — useful after changing a naming template.

Setup

  1. count is the batch size ("" = everything); radarr_count / sonarr_count / lidarr_count override it when above 0.
  2. tag_name spreads a large library over several runs: each checked item is tagged, untagged items go first, and once all are tagged the tags are cleared and the cycle restarts.
  3. enable_batching: true runs every batch in one go (batch size count, or 100). Off, a run does one batch.
  4. ignore_tags (comma-separated) skips items.
  5. refresh_before_rename: true refreshes each item first so renames pick up new titles (for example Sonarr TBA episodes). Slower; skipped on dry runs.

Folder renames ask the ARR for each folder's name first. A folder is left alone when the new name is taken, when it sits in a subfolder of its root folder, or when the new name would drop its year, an id or its title (usually missing metadata). The summary counts these and the log says why. A dry run lists the folder renames it would make.

Checks: it waits for any running ARR refresh before renaming or moving, then checks each renamed item's files. It refreshes only items whose records no longer match their files, never while a file is missing. A missing file stops the run for that instance and is listed in the summary.

Config

renameinatorr:
  dry_run: false
  log_level: info
  rename_folders: true
  refresh_before_rename: false
  count: 100                            # integer, or "" = all items
  radarr_count: 0                       # 0 = use count
  sonarr_count: 0
  lidarr_count: 0                       # artists
  tag_name: renamed                     # default ""; "" = no tagging
  ignore_tags: ""
  enable_batching: false
  instances: [radarr_main, sonarr_main, lidarr_main]

🩺 health_checkarr

Reads each ARR's health feed for items removed from TMDB/TVDB (Radarr RemovedMovieCheck, Sonarr RemovedSeriesCheck) and deletes them from the ARR. Radarr and Sonarr only. Preview with dry_run: true first.

Config

health_checkarr:
  dry_run: false
  log_level: info
  instances: [radarr_main, sonarr_main]

🪺 nestarr

Reports library problems; never moves or deletes:

  1. Unmatched — items in the ARR but not Plex, or in Plex but in no ARR, from a fresh Plex walk. Only libraries in library_mappings; off without mappings.
  2. Nested paths — tracked media inside another item's folder, usually a botched import.
  3. Strays — folders or video files in an ARR root folder that no item tracks.
  4. File records (Radarr/Sonarr) — video files in a tracked folder the ARR doesn't know about, and recorded files missing from disk.

Add path_mapping when the ARR and CHUB see media at different paths. Results also show on Library → Manage → Unmatched & Nested Media, which can start a scan.

Config

nestarr:
  log_level: info
  library_mappings:
    - arr_instance: radarr_main
      plex_instances:
        - instance: plex_main
          library_names: ["Movies"]
  path_mapping:                         # ARR path → CHUB path
    - arr_path: /media/movies
      local_path: /data/movies

☁️ sync_gdrive

Pulls poster assets from Google Drive folders into local folders with rclone.

Authentication

  • gdrive_sa_location — a service-account JSON keyfile, used whenever the file exists.
  • Otherwise your own OAuth client_id / client_secret (shown when no keyfile path is set).
  • token — OAuth token JSON that signs in as you, needed for uploads (e.g. from the CL2K maker) because a service account can't own files in a personal Drive. Get one with rclone authorize "drive" (add "CLIENT_ID" "CLIENT_SECRET" for your own client) and paste the whole JSON.

⚠️ rclone's shared client ID is going away. With no readable keyfile and no client ID of your own, rclone falls back to its built-in client, which shares one 10 requests/sec quota with every rclone user and is retired during 2026. The settings page warns when this applies. Use a keyfile or create your own client ID. For service accounts, see the DAPS wiki's rclone guide.

Drives: add each folder to gdrive_list with a name, id and location, or pick from Gdrive Presets (the bulk picker adds several; CHUB tells you when an update adds presets). Drives are poster_renamerr sources automatically; turn on Browse only (search_only) for "Extras" drives you only want in Assets Search. Removing a drive deletes its local folder if it's empty (prune_orphan_drives); one that still holds files is reported.

Gotcha: a drive's location and id, and gdrive_sa_location, can't contain a null byte or start with -.

Config

sync_gdrive:
  dry_run: false
  log_level: info
  verbose: false                        # log every file rclone copies, deletes or renames
  gdrive_sa_location: /config/gdrive-sa.json
  # client_id: "<oauth-client-id>"
  # client_secret: "<oauth-client-secret>"
  # token: "<rclone-token-json>"
  prune_orphan_drives: true             # YAML only
  gdrive_list:
    - name: "Community poster mirror"
      id: "<google-drive-folder-id>"
      location: /posters/gdrive/community
      search_only: false

🧼 plex_maintenance

Plex housekeeping on its own schedule, for the whole server (regardless of the libraries opted in on Settings → Instances). Four tasks, all off by default:

  • empty_trash — permanently removes items Plex has marked deleted.
  • clean_bundles — drops orphaned .bundle folders.
  • optimize_db — VACUUMs Plex's database. The slowest; run it monthly.
  • photo_transcoder — deletes Plex's Cache/PhotoTranscoder/ files directly; works even if Plex is unreachable. Needs plex_path (the same value as poster_cleanarr); empty = skipped.

Cancel stops photo_transcoder, but the three Plex tasks run to completion — restart the container to kill one.

Config

plex_maintenance:
  log_level: info
  dry_run: false
  empty_trash: true                     # all four default to false
  clean_bundles: true
  optimize_db: false
  photo_transcoder: true
  plex_path: /plex
  sleep: 60                             # seconds between tasks
  timeout: 600                          # Plex connection timeout (seconds)
  instances: [plex_main]

Next: Configuration · Related: Kometa Integration, UI Guide

Clone this wiki locally