Repository navigation
Modules
🏠 Home › 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.
🧩
fullimage extensions.cl2k_makerandposter_self_healship only in thefullimage (ghcr.io/chodeus/chub:full, orvX.Y.Z-full). Onlatestthey 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)
-
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_assetsandnestarrare report-only and have none. -
Log level —
debug(each item's decision) orinfo(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_cleanarrreporting daily and removing weekly). See Configuration → schedule.
| 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 |
| 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 |
| Module | What it does | Cancellable | Report-only |
|---|---|---|---|
plex_maintenance |
Plex housekeeping (trash, bundles, DB, photo cache) | Partial | No |
| 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) |
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
- Set
apply_method:kometa(write renamed files todestination_dir) orplex(upload to Plex). - 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. - List
instances(Radarr/Sonarr/Lidarr) — they supply the media list. - Pick Plex libraries under Plex Libraries (
plex_scope). For theplexmethod, turn on Upload posters to this Plex instance. Match collections in selected libraries matches collection posters (no libraries picked = all enabled libraries). - Optionally chain
run_border_replacerr,run_asset_renamerr,clean_orphan_assetsandreport_unmatched_assets.
Every Sync GDrive drive is a source automatically, unless it's set to Browse only. Drives you don't list in
source_dirsare 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.
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 falseApplies 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
- Pick the Primary Source:
localfiles first (fanart.tv fills gaps) orfanartfirst (local files fill gaps). - 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.
- Pick
asset_types,apply_methodandaction_type, theninstances(Radarr/Sonarr) andplex_scopeas forposter_renamerr. - 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
plexmethod, art goes to every library the item lives in (e.g. both 1080p and 4K). Onkometa,asset_foldersmust match Kometa's andposter_renamerr's — Kometa has one global toggle, so a mismatch leaves half the tree unread. CHUB warns when the modules disagree.
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 hereRe-applies a brand or holiday border to matched posters. Not cancellable — restart the container to stop a big run.
-
Color mode — crops
border_widthpx off each edge and paints a flat border, cycling throughborder_colors(or the active holiday'scolors). -
Image mode — when the active holiday has
borders:, composites a 1000×1500 decorative PNG over the poster;border_widthis ignored. -
Remove mode — no
border_colorsand 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.
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 |
Browse the full set in backend/assets/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.
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🧩
fullimage 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.
▶ 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
- 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 toposter_renamerr.source_dirsso generated posters get applied. - Optionally add Drive uploads (
gdrive_uploads) the same way, with a Drivefolder_id. They use the Sync GDrive OAuth token (a service account can't own files in a personal Drive). - Tune
whiten_logo,text_logo_fallbackandtext_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_renamerrwon't apply them.poster_self_healstill covers them.
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, …).
🧩
fullimage only. Needscl2k_makerand 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.
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 runAPI: /api/poster-self-heal/* (reviews, count, coverage, reviews/{id}/apply, reviews/{id}/dismiss).
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_librariesskips whole libraries (handy for Music, whose album art otherwise shows as(unknown)); it can only reduce what's deleted.overlays_only: trueskips 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_instancesfirst and skips the pass if that fails.include_collectionskeeps collection posters;orphan_ignore_titlesexempts 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_pathis the container path of the Plex Media Server data folder — the one containingMetadata/,Cache/andPlug-in Support/. Mount the host'sLibrary/Application Support/Plex Media Server/at, say,/plexand 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.
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: reportMirrors 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.
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"]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_databasecan't contain a null byte or start with-, and its parent folder must exist.
jduparr:
dry_run: false
log_level: info
hash_database: /config/jduparr.db # default none
source_dirs: [/media/movies, /media/tv]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.
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]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).
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"]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:
-
countandsearch_mode:upgrade(every untagged item),missing(no file), orcutoff(below the quality cutoff). - An optional
label, anenabledswitch, and an optional ownschedule(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: trueclears 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_thresholdis 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.
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: upgradeApplies each ARR's own naming scheme to existing files and folders in Radarr, Sonarr and Lidarr — useful after changing a naming template.
Setup
-
countis the batch size (""= everything);radarr_count/sonarr_count/lidarr_countoverride it when above 0. -
tag_namespreads 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. -
enable_batching: trueruns every batch in one go (batch sizecount, or 100). Off, a run does one batch. -
ignore_tags(comma-separated) skips items. -
refresh_before_rename: truerefreshes each item first so renames pick up new titles (for example SonarrTBAepisodes). 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.
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]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.
health_checkarr:
dry_run: false
log_level: info
instances: [radarr_main, sonarr_main]Reports library problems; never moves or deletes:
-
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. - Nested paths — tracked media inside another item's folder, usually a botched import.
- Strays — folders or video files in an ARR root folder that no item tracks.
- 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.
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/moviesPulls 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 withrclone 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
locationandid, andgdrive_sa_location, can't contain a null byte or start with-.
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: falsePlex 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.bundlefolders. -
optimize_db— VACUUMs Plex's database. The slowest; run it monthly. -
photo_transcoder— deletes Plex'sCache/PhotoTranscoder/files directly; works even if Plex is unreachable. Needsplex_path(the same value asposter_cleanarr); empty = skipped.
Cancel stops photo_transcoder, but the three Plex tasks run to completion — restart the container to kill one.
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
