Lifecycle Rules

The lifecycle rule engine lets you define conditions to automatically identify and act on media in your library. It uses a flexible rule group structure with AND/OR logic.

Concepts

Rule Sets

A rule set is a named collection of rules and actions. Each rule set targets a specific media type (movies, series, or music).

Rule Groups

Rules are organized into groups. Each condition (and each nested sub-group) connects to the one above it with AND or OR:

• AND: must match together with everything above it
• OR: matches if either side does

When a group uses a single connector throughout, this reads exactly as you’d expect — all conditions must match (AND) or any condition may match (OR). When AND and OR are mixed, conditions combine top to bottom, each connector applying to the combined result of everything above it — so A OR B AND C means (A OR B) AND C. The builder shows a hint whenever this applies, and the Logic Preview panel beside the builder always spells out the exact grouping with parentheses (hovering a condition highlights its line in the preview).

Groups can be nested to make grouping explicit — a sub-group is evaluated on its own first, then joins its parent as a single result.

Rules

Each individual rule consists of:

1. Field — what property to evaluate (e.g., playCount, resolution, addedAt)
2. Operator — how to compare (e.g., equals, greaterThan, before)
3. Value — the target value

Negation is part of the operator choice: alongside each comparison the picker offers its inverse — Not Equals, Not Contains, Not Greater Than, Not Between, and so on.

Whole groups can be negated too. Every group has a NOT toggle that inverts its entire result — for example NOT (watched by Alice OR watched by Bob) matches items watched by neither. The Logic Preview shows the negation in place, and items the group would have matched are excluded instead. (Stream query groups negate through their quantifier rather than a NOT toggle.)

Stream query groups

A Stream Query group tests an item’s individual audio, video or subtitle tracks instead of the item’s summary fields, so every condition inside it is checked against the same track — “an English audio track that is also Dolby Atmos”, not “an English track and, separately, an Atmos one”. It reads one episode’s or track’s file, so it isn’t offered while a Series or Music rule set judges whole shows or artists (see Series scope and aggregate fields). The group reads <quantifier> <stream type> stream where …:

Quantifier	Matches an item when…
ANY	at least one track of that type meets every condition in the group
NO	no track of that type meets them (an item with no track of that type matches)
ALL	it has at least one track of that type, and every one of them meets the conditions

A stream query inside a group with NOT is inverted exactly: under NOT, ANY becomes NO and NO becomes ANY, and ALL becomes “some track of that type fails a condition” — NOT (ALL audio stream where Language is English) matches an item with at least one audio track that is not English. An item with no track of that type matches neither ALL nor its NOT.

Each stream type offers only the fields its tracks carry:

Label	Field	Stream types
Codec	sqCodec	audio, video, subtitle
Profile	sqProfile	audio, video, subtitle
Language	sqLanguage	audio, video, subtitle
Language Code	sqLanguageCode	audio, video, subtitle
Bitrate (kbps)	sqBitrate	audio, video
Is Default Track	sqIsDefault	audio, video, subtitle
Display Title	sqDisplayTitle	audio, video, subtitle
Extended Display Title	sqExtDisplayTitle	audio, video, subtitle
Channels	sqChannels	audio
Sample Rate (Hz)	sqSamplingRate	audio
Channel Layout	sqAudioLayout	audio
Audio Profile	sqAudioProfile	audio
Bit Depth	sqBitDepth	video
Width	sqWidth	video
Height	sqHeight	video
Frame Rate	sqFrameRate	video
Scan Type	sqScanType	video
Video Range Type	sqVideoRangeType	video
Dynamic Range	sqDynamicRange	video
Color Primaries	sqColorPrimaries	video
Color Range	sqColorRange	video
Chroma Subsampling	sqChromaSubsampling	video
Forced	sqForced	subtitle

In rule JSON a stream query group is a group with a streamQuery object — { "streamType": "audio", "quantifier": "any" } (any, none or all) — whose conditions use the fields above. Changing a group’s stream type clears its conditions, since the fields differ.

Limiting how much one run can delete

By default there is no limit. Librariarr is built to run unattended, and if your rules legitimately select thousands of items, it deletes thousands of items — that is the point of the tool, not a bug to guard against.

You can opt into a ceiling under Settings → General → Delete without asking, up to N items per run. A run that would delete more than N is held: nothing is deleted, the actions stay on the Pending page, and you execute them from there once you have looked at them. That review step is the approval — there is no separate queue to manage.

What it is for is worth being precise about. It is not a safety net for a rule you wrote wrong; a rule that selects 40 items you did not mean will happily delete 40 items under a limit of 50. It bounds the other case — where something upstream of the rule is wrong and the match set is far larger than anything you intended. Librariarr already refuses to evaluate rules whose evidence is missing (unavailable Arr metadata, unestablished play history), but those guards each cover a hazard someone found. A ceiling covers the ones nobody has found yet.

Details worth knowing:

• Deletions only. Unmonitor, tag and search actions never count toward it and are never held.
• Per run, across every rule set — one number for the whole execution pass.
• Counted after the safety checks, not before. The figure is what the run would actually delete, so actions about to be cancelled anyway — the item stopped matching, it (or a sibling) is on the exception list, the item’s identity changed since it was scheduled — are not counted, and they are still cleaned up even on a run the ceiling holds.
• All-or-nothing. Exceeding the limit holds the entire batch rather than deleting up to the limit. Acting on an arbitrary slice of a match set you already have reason to distrust is not safer.
• It applies to manual bulk actions too — Execute and Execute All on the Pending page and the Query page’s actions — not just scheduled runs.
• If you have a Discord webhook configured, a held run notifies you, so it cannot fail silently.

Available Fields

Over 80 fields are available for rule conditions. Fields that can never have a value for a library type (for example Sonarr’s season count on a movie rule set) are disabled in the builder, and a rule set that uses one anyway is refused when saved.

A criterion whose value belongs to one episode or one track can never make a whole show or artist the target of an action. So fields that describe one file, or one episode or track, can’t be used while a Series or Music rule set judges whole shows or artists (Match against entire series or Match against entire artist on): Year, Release Date (originallyAvailableAt), Rating, Audience Rating, Rating Count, Album, Duration, Genre, Studio, Content Rating, Label, Country, Is Watchlisted, every video and audio field (Audio Language, Stream Audio Codec and Audio Track Count included), Container, Subtitle Language, Subtitle Track Count, stream query groups, and, on a Music rule set, Has External ID. With the scope off they are checked per episode or track — but not under an action that acts on the whole show or artist (Delete from Sonarr or Lidarr, Change Quality Profile, Arr tags, …), which may then follow only what every episode or track of it answers alike. The builder shows them disabled, and a rule set using one is refused when saved. Movie rule sets can use them all — see Series scope and aggregate fields.

Each table gives the Label the rule editor shows and the Field name it stands for. Use the field name wherever a rule is written as data: the field of a condition in an exported or imported rule set (see the Rule Set Library), and in the JSON sent to the rule set and query routes.

Media Fields

Label	Field	Description	Operators
Play Count	playCount	Number of times played	equals, greaterThan, lessThan, etc.
Watched By User	watchedByUser	Server username that played the item (Plex/Jellyfin/Emby) — multi-select	equals, notEquals, contains, notContains, matchesWildcard, isNull, isNotNull
Last Played	lastPlayedAt	When last played	before, after, inLastDays
Date Added	addedAt	When added to library (Date Added)	before, after, inLastDays
Release Date	originallyAvailableAt	Release Date reported by the media server (a calendar day)	before, after, inLastDays
Is Watchlisted	isWatchlisted	On your Plex watchlist (Plex) or marked favourite (Jellyfin/Emby)	equals, notEquals
Title	title	Media title	equals, contains, matchesWildcard
Artist / Series	parentTitle	Artist / Series — the series name for an episode, the artist for a track. A show or artist evaluated as a whole (series scope, artist scope, or a rule with a series criterion) reads its own name, so Artist / Series Not Equals “Doctor Who” leaves out Doctor Who and nothing else	equals, contains, matchesWildcard
Album	albumTitle	Album (music)	equals, contains, matchesWildcard
Year	year	Release year	equals, greaterThan, lessThan, etc.
Content Rating	contentRating	Content rating (PG, R, etc.)	equals, notEquals
Rating	rating	Critic rating	greaterThan, lessThan, etc.
Audience Rating	audienceRating	Audience rating	greaterThan, lessThan, etc.
Rating Count	ratingCount	Rating Count — Plex’s ratingCount, the number of ratings behind the item’s rating in Plex’s online metadata. Plex sets it mostly on music tracks (a popularity count); it is empty for Jellyfin and Emby items and for most movies and episodes, so pair it with Is Empty or a media-type check	greaterThan, lessThan, etc.
Studio	studio	Production studio	equals, contains
Genre	genre	Genre(s)	equals, contains
Label	labels	Label tags set on the media server	equals, contains
Country	country	Country of origin — multi-select (movies only)	equals, contains, notContains
Duration (min)	duration	Duration in minutes	greaterThan, lessThan, etc.
Has External ID	hasExternalId	Which external-id sources the item carries (TMDB, TVDB, IMDB, MUSICBRAINZ) — multi-select	equals, notEquals, contains, notContains, matchesWildcard, isNull, isNotNull

hasExternalId: per-source vs. “any at all”

Operators that take a value ask a per-source question: equals TMDB matches items carrying a TMDB id. Is Empty / Is Not Empty take no value, so they ask about the whole list — Is Empty means “no external ids at all”. For “has no TMDB id specifically”, use notEquals TMDB.

Video Fields

Label	Field	Description
Resolution	resolution	4K, 1080P, 720P, etc.
Video Codec	videoCodec	H.264, H.265, AV1, etc.
Video Bitrate (kbps)	videoBitrate	Video bitrate (kbps)
Video Bit Depth	videoBitDepth	8-bit, 10-bit
Video Profile	videoProfile	Baseline, Main, High
Frame Rate	videoFrameRate	Frame rate (23.976, 24, etc.)
Aspect Ratio	aspectRatio	16:9, 4:3, 2.39:1, etc.
Dynamic Range	dynamicRange	SDR, HDR10, HDR10+, Dolby Vision, HLG
Scan Type	scanType	progressive, interlaced

Audio Fields

Label	Field	Description
Audio Codec	audioCodec	AAC, AC3, FLAC, etc.
Audio Channels	audioChannels	Channel count (2, 6, 8, etc.)
Audio Profile	audioProfile	Dolby Atmos, DTS-HD MA, etc.
Sample Rate (Hz)	audioSamplingRate	Sampling rate in Hz (48000, etc.)
Audio Bitrate (kbps)	audioBitrate	Audio bitrate (kbps)
Audio Language	audioLanguage	Audio track language
Stream Audio Codec	streamAudioCodec	Codec of any audio track (not only the primary one)
Audio Track Count	audioStreamCount	Number of audio tracks

File Fields

Label	Field	Description
File Size (MB)	fileSize	File size (in MB)
Container	container	File container (MKV, MP4, etc.)
Subtitle Language	subtitleLanguage	Subtitle track language
Subtitle Track Count	subtitleStreamCount	Number of subtitle tracks

Cross-System Fields

Label	Field	Description
Server Count	serverCount	Number of copies of the item across your servers (items sharing its dedup identity)
Matched By Rule Set	matchedByRuleSet	Names of the rule sets currently matching the item — multi-select
Has Pending Action	hasPendingAction	Whether another rule set already has an action pending on the item or another copy of it

Episode Fields

Series rule sets (and Series on the Query page) only. These are judged on each episode, so a rule set using one must have series scope off, and its action must act only on the matched episodes (Delete Files Only, Unmonitor Only, Search for New Copy or Do Nothing, without tags) — see Season and episode criteria.

Label	Field	Description
Season Number	seasonNumber	The episode’s season number (specials are season 0)
Episode Number	episodeNumber	The episode’s number within its season
Seasons Behind Latest	seasonsBehindLatest	How many seasons the episode’s season is behind the show’s newest season in your library: 0 for the newest season, 1 for the one before, and so on. Specials and episodes without a season number have no value

Series Fields

Series rule sets only. See Series scope and aggregate fields.

Label	Field	Description
Available Episode Count	availableEpisodeCount	Episodes of the show in your library
Watched Episode Count	watchedEpisodeCount	Episodes played at least once
Watched Episode %	watchedEpisodePercentage	Share of the show’s episodes played, as a percentage
Series Last Played	seriesLastPlayedAt	Series Last Played — most recent play of any episode
Latest Episode View Date	latestEpisodeViewDate	Last play of the newest episode
Last Episode Added	lastEpisodeAddedAt	When the newest episode was added
Last Episode Aired	lastEpisodeAiredAt	Air date of the newest episode (a calendar day)

Calendar-day fields

originallyAvailableAt, arrReleaseDate, arrInCinemasDate, arrFirstAired and lastEpisodeAiredAt are calendar days rather than moments in time, and are shown as that day wherever you are. Other date fields (added, last played, request dates) are moments and are shown in your local time.

External / *arr Fields

These fields require configured Sonarr, Radarr, or Lidarr integrations.

Label	Field	Description
Found In Arr	foundInArr	Whether the item exists in the linked *arr instance
Monitored	arrMonitored	Whether monitored in *arr
Tag	arrTag	Tags in *arr instance
Quality Profile	arrQualityProfile	Quality profile name
Quality Name	arrQualityName	Name of the current file’s quality (Radarr / movies only)
Quality Cutoff Met	arrQualityCutoffMet	Whether the current file meets the quality profile’s cutoff (Radarr / movies only). true once the file is at or above the cutoff, so no upgrade is pending
Custom Format Score	arrCustomFormatScore	Custom format score of the movie’s current file (Radarr / movies only)
Status	arrStatus	Release/lifecycle status in *arr (e.g. released, continuing)
Ended	arrEnded	Whether the series has ended (Sonarr / series only)
Series Type	arrSeriesType	Series type: standard, daily, or anime (Sonarr / series only)
IMDB Rating	arrRating	IMDB Rating in *arr. For movies this is the IMDB rating; for series/music it is the single aggregate rating the *arr exposes
TMDB Rating	arrTmdbRating	TMDB rating in *arr (Radarr / movies only — Sonarr/Lidarr expose only a single flat rating)
RT Critic Rating	arrRtCriticRating	Rotten Tomatoes critic rating in *arr (Radarr / movies only — Sonarr/Lidarr expose only a single flat rating)
Original Language	arrOriginalLanguage	Original language in *arr (not music)
Runtime (min)	arrRuntime	Runtime in minutes (Radarr / movies only)
Size on Disk (MB)	arrSizeOnDisk	Size on disk in MB
Path	arrPath	File path in *arr
Release Date	arrReleaseDate	Digital/physical release date (Radarr / movies only)
In Cinemas Date	arrInCinemasDate	In-cinemas date (Radarr / movies only)
First Aired	arrFirstAired	First-aired date (Sonarr / series only)
Date Added	arrDateAdded	When the item was added to *arr
Download Date	arrDownloadDate	When the current file was downloaded (Radarr / movies only)
Season Count	arrSeasonCount	Total season count (Sonarr / series only)
Episode Count	arrEpisodeCount	Total episode count, specials excluded — every episode Sonarr knows of, aired or not, monitored or not (Sonarr / series only)
Has Unaired	arrHasUnaired	Whether the series has an episode airing in the future, monitored or not, or is still upcoming (Sonarr / series only)
Monitored Seasons	arrMonitoredSeasonCount	Number of monitored seasons, specials excluded (Sonarr / series only)
Monitored Episodes	arrMonitoredEpisodeCount	Number of episodes in monitored seasons, specials excluded. Sonarr reports no per-episode monitored count with the series, so an episode unmonitored inside a monitored season is still counted (Sonarr / series only)

Missing *arr data is fail-closed

If an item isn’t in the linked *arr instance, or a specific field has no value (for example a movie with no downloaded file has no quality name, quality-cutoff, or size), no comparison operator matches it — including negative operators like Not Equals / Not Contains and the NOT toggle. This is deliberate so lifecycle rules never delete an item on the strength of absent *arr data. To target items with missing data, use the Is Empty (isNull) operator, or the foundInArr field.

*arr criteria need at least one enabled instance

If you disable or delete your only Radarr, Sonarr, or Lidarr instance, rule sets using that family’s fields are skipped entirely by detection, with a warning in System Logs, and previews return an error. This is deliberate: without an instance to check against, foundInArr = false would be true for your whole library. Re-add the instance and the rule set resumes on the next detection run.

When a rule set’s action is linked to an *arr instance, its *arr criteria are read from that instance only — the same one its action runs against. With a 1080p and a 4K Radarr, a rule set acting on the 4K instance sees the 4K copy’s tags, monitored state and quality profile, never the 1080p copy’s. If that instance is disabled, the rule set is skipped in the same way, even while another instance of the family is enabled. The editor requires an instance for a rule set that uses *arr fields (an “… instance required” warning disables Preview, Test Media and Save until you pick one). A rule set saved without one, such as an older one, reads every enabled instance; a title on more than one of them takes the record from the instance that was added first. Changing the *arr instance of a rule set that uses *arr criteria clears its matches and cancels its pending actions, since they were judged on the old instance; the editor asks how to handle matches as it does for a rule change.

Seerr Fields

These fields require a configured Seerr integration.

Label	Field	Description
Has Request	seerrRequested	Whether requested in Seerr
Request Date	seerrRequestDate	When the most recent request was made
Request Count	seerrRequestCount	Number of requests
Requested By	seerrRequestedBy	Who requested it
Approval Date	seerrApprovalDate	When the most recent request was approved (including requests Seerr has since marked Completed or Failed)
Decline Date	seerrDeclineDate	When the most recent request was declined

An item with no such date (never requested, never approved, never declined) fails every date comparison except Not Equals, exactly like the library’s own date fields, and Not then applies as usual — so NOT (Request Date in the last 90 days) includes titles nobody ever requested, while NOT (Request Date not equal to a date) does not. Use Is Empty / Is Not Empty to target them directly. If Seerr’s request list can’t be read in full, rule sets using Seerr fields are skipped for that run rather than evaluated against a partial list.

Seerr criteria need a connected Seerr instance

With no Seerr instance connected — after importing a rule set, say — the rule builder shows a “Seerr instance required” warning and disables Preview, Test Media, and Save until you connect one under Settings → Integrations. Detection skips such rule sets too, for the same reason as *arr fields above.

Seerr fields work on movie and series rule sets only; Seerr doesn’t manage music requests, so music rule sets reject them at save time. A music rule set that somehow already carries Seerr criteria is disarmed — its matches are cleared and its pending actions cancelled.

Operators

Operator	Label	Applicable Types	Description
equals	Equals (dates: Is On)	text, number, date, boolean	Exact match
notEquals	Not Equals (dates: Is Not On)	text, number, date, boolean	Not an exact match
greaterThan	Greater Than	number	Greater than value
greaterThanOrEqual	>=	number	Greater than or equal
lessThan	Less Than	number	Less than value
lessThanOrEqual	<=	number	Less than or equal
contains	Contains	text	For free-text fields (e.g. title, path): substring match (case-insensitive). For enumerable fields (e.g. quality profile, tag, codec) the operator presents a multi-select and matches if the item’s value equals any selected value (list membership, not substring).
notContains	Not Contains	text	Inverse of contains — same free-text vs enumerable distinction.
matchesWildcard	Matches Wildcard	text	Wildcard match (* = any characters, ? = single character)
notMatchesWildcard	Not Matches Wildcard	text	Does not match wildcard pattern
before	Is Before	date	Before a specific date
after	Is After	date	After a specific date
inLastDays	In Last X Days	date	Within the last N days
notInLastDays	More Than X Days Ago	date	More than N days ago
between	Between	number, date	Within an inclusive range
isNull	Is Empty	text, number, date (and the booleans *arr may leave unset: arrQualityCutoffMet, arrEnded, arrHasUnaired)	The item has no value for this field (takes no value of its own)
isNotNull	Is Not Empty	same as Is Empty	The item has some value for this field (takes no value of its own)

Boolean fields (isWatchlisted, foundInArr, hasPendingAction and so on) take Equals / Not Equals true or false.

All text comparisons are case-insensitive, including genres, labels and countries. Servers do not agree on casing — one may report Sci-Fi where another reports sci-fi, and the dropdown lists both — so a rule written against either spelling matches copies on every server.

What “Is Empty” means per field

Is Empty / Is Not Empty take no value; what counts as “empty” depends on the field’s shape:

Field shape	Examples	Is Empty matches
Nullable column	studio, rating, lastPlayedAt, arrQualityName, arrEnded	The value is missing
List	genre, labels, country, arrTag, seerrRequestedBy, watchedByUser, matchedByRuleSet	The list has no entries — e.g. an item that is in *arr but carries no tags
Always-present text	title, arrQualityProfile	The value is the empty string

Fields whose value is always present and has no meaningful “empty” reading — foundInArr, arrMonitored, seerrRequested, seerrRequestCount, playCount, isWatchlisted, serverCount, hasPendingAction — don’t offer the two operators at all, because Is Not Empty on them would just match everything.

List fields ask about membership

On a list field, every operator compares case-insensitively, and Equals / Contains ask whether a value is in the list — not whether it appears inside one: Tag Contains "kee" does not match the tag Keep, but Tag Matches Wildcard "kee*" does.

arrTag Is Empty means “in *arr, but carries no tags”. An item that isn’t in *arr at all doesn’t match it — use foundInArr for that question.

Audio and subtitle language are fail-closed

An item with no known language for a track type — no track at all, or only tracks the server reports as Unknown — matches no language rule, positive or negative. Subtitle Language Is Not English finds items that have a subtitle track in another language; for items with no subtitles at all, use Subtitle Language Is Empty. Wrapping the rule (or its group) in NOT does not change this: NOT (Audio Language Is English) still skips items with no audio track, rather than sweeping them in.

Track codec fields have no such placeholder, so they read plainly: an item with no audio track does match Stream Audio Codec Is Not AAC.

Building Rules

Using the Rule Builder

1. Create a Rule Set: Give it a name and select the target media type
2. Add rules: Select a field, operator, and value
3. Group rules: Use AND/OR groups to combine conditions
4. Nest groups: Create sub-groups for complex logic
5. Toggle rules: Enable/disable individual rules or groups without deleting them
6. Negate: Pick a “Not …” operator to invert a condition, or flip a group’s NOT toggle to invert the whole group
7. Reorder: Drag rules to change their position within a group

Example: Identify Old, Unwatched Movies

Create a rule set with an AND group containing:

• playCount equals 0 — Never watched
• addedAt before 2023-01-01 — Added over a year ago
• resolution notEquals 4K — Not 4K quality

Example: Find Duplicate Quality

Create a rule set with an OR group:

• resolution equals 480P
• resolution equals SD
• videoCodec equals mpeg2video

Example: Clear Out Older Seasons

Keep the two newest seasons of every show and free the space taken by the rest. Create a Series rule set, turn Match against entire series off, and add:

• seasonsBehindLatest greaterThanOrEqual 2 — Every season older than the two newest
• playCount greaterThan 0 — Already watched (optional)

With the action Delete Files Only, the files of each show’s older seasons are deleted, while the two newest seasons are left alone (Sonarr’s Unmonitor Deleted Episodes setting, or a second rule set with Unmonitor Only, keeps Sonarr from downloading them again). Unmonitor Only unmonitors those episodes and keeps the files. Unmonitor & Delete Files can’t be used here: it unmonitors the whole series in Sonarr, newest seasons included, so the editor offers it disabled (see Season and episode criteria). When a new season arrives, the window moves with it on the next run. Use seasonNumber instead to target fixed seasons (for example seasonNumber between 1,3).

Example: Watched Only By Departed Household Members

Create a rule set with an AND group:

• watchedByUser contains alice|bob — Only watched by people no longer in the household
• watchedByUser notContains carol|dave — Never watched by current household members
• addedAt notInLastDays 180 — Been in the library for at least 6 months

The watchedByUser field reads from the per-user play history synced from Plex / Jellyfin / Emby. “Watched by” means any counted play by that user: every play the media server’s own history records, and, for history imported from Tracearr, only plays that reached Tracearr’s completion threshold. The dropdown is populated with usernames that have at least one counted play on your connected servers — a user whose only Tracearr plays stopped short of Tracearr’s completion threshold is not offered, since no rule could match them.

Switching between rule sets

Saved rule sets are always within reach of the editor, so switching never means scrolling back to the top of a long rule set:

• Wide screens with a mouse or trackpad: a slim strip beside the editor shows each rule set as a coloured monogram (the one being edited is outlined, an amber dot marks an armed action, a faded one is disabled). It stays in place while the editor scrolls. Hover over it — or tab into it — and it opens over the editor with each rule set’s name, its feature chips, an on/off switch and a delete button; move away (or press Esc) and it folds back. The pin button at its top keeps it open beside the editor instead.
• Phones, tablets and narrower windows: a bar pinned to the top of the editor names the rule set being edited (Rule set 3 of 12). The arrows step to the previous or next rule set, and tapping the name opens the full list as a sheet.

With six or more rule sets the list adds a filter box that narrows it by name. Switching away from a rule set with unsaved edits asks before discarding them, and New Rule Set asks the same.

Building rules on the Query page

The Query Builder at /library/query uses this same builder and engine to search your library on demand. A query you’d like enforced on a schedule can be turned into a rule set with Convert to Lifecycle Rule — see Converting a query into a rule set. The Query page can also run an action on its results straight away, without a rule set and without the action delay — see Running actions on results.

Importing and Exporting Rule Sets

Export, beside Save in the rule editor, shows the rule set as JSON to copy: its rules and groups, the action and its options, the collection settings, the Discord toggles and Sticky matches. Import takes that JSON back — on the tab matching the rule set’s type — and fills the editor with it as a new, unsaved rule set.

Two things are deliberately left out of an export because they belong to one install: the *arr instance (and, for Change Quality Profile, the quality profile, whose id is specific to that instance) and the servers the rule set targets. After an import you pick the Media Servers and the *arr server at the top of the editor — an import targets no server, and Preview and Save wait until it does. Collection settings import as + Create new collection… with the exported name; if a collection of that name already exists for the library type, saving is refused as a duplicate, so pick the existing one in the Collection dropdown instead.

The Rule Set Library has ready-made rule sets in this format.

Previewing Matches

Before executing any actions, use the Preview feature to see which media items match your rules:

• Shows a count of matching items, in a card or table view
• On an existing rule set, marks each item as new, retained or removed compared with its current matches
• Runs when you click Preview (and Test Media checks one item of your choice against the rules)
• Shows a live progress bar through each phase (fetching *arr/Seerr metadata, evaluating rules, computing matched criteria) so large libraries don’t just spin
• Reuses the *arr and Seerr data it fetched for 45 seconds, so Preview, Test Media and the Match Changes Preview of Save and re-detect, pressed one after another, share one read of your *arr and Seerr libraries instead of each reading them again. A change made in Sonarr, Radarr, Lidarr or Seerr (a tag added there, say) can therefore take up to 45 seconds to show in a preview. Adding, editing or removing an *arr or Seerr instance in Librariarr discards the kept data at once, and running actions discards the *arr data. Detection and the actions themselves never use it: they always read fresh data.
• Test Media asks each *arr instance for the one item being tested rather than its whole library, unless a preview has just fetched the library anyway
• Radarr’s Custom Format Score is fetched only for a rule set that uses it, since it is the slowest part of reading Radarr (one request per 100 movies)

Preview is refused whenever the rules can’t be evaluated faithfully, and the reason is shown as an error notification rather than an empty or stale result list. The same guard that pauses detection applies here, so a preview never shows matches that detection would refuse to produce:

• *arr criteria with no enabled Sonarr/Radarr/Lidarr instance, or Seerr criteria with no enabled Seerr instance (Seerr criteria on a music rule set are refused permanently).
• Criteria that describe one episode or track in a rule set with Match against entire series or Match against entire artist on — see Series scope and aggregate fields. The editor turns Preview, Test Media and Save off in that case, and also while such criteria are followed by an action on the whole show or artist with the scope off, so this reaches you only from a rule set saved before the rule existed.
• Criteria that read play activity — Watched By User, Play Count, Last Played, and the series rollups built on them — while any targeted server’s play history isn’t established yet: it has never synced, was recently cleared, or a Tracearr history import is still backfilling. Until the history is known, every item looks never-watched, so Play Count = 0 or not played in N months would match the entire library. The warning names the server and which of those applies: a server that is still importing clears itself when the import finishes (Settings → Media Servers shows its progress), while one where no sync has established what was played clears on the next successful watch-history sync — run one from Library → History → Refresh.

The last case also shows a “Play history not established yet” warning in the rule editor, naming the servers involved, so you can see a rule set is paused without having to run anything. It clears itself when the import finishes — no reload needed. The same warning pattern already covers a missing *arr or Seerr instance.

Saving with Save and re-detect (then Confirm and Save) reports the same thing: if detection refuses the rule set, you stay on the editor with the reason rather than being sent to Matches, where the previous run’s matches would otherwise look like the new result.

Re-evaluate and Re-evaluate All on the Matches page report it too. A refused rule set keeps the matches it already had — detection preserves them deliberately — so its row is left as it was and a notification names the rule set and the reason. It is not shown as having zero matches; that would be the opposite of what happened.

Actions

Actions determine what happens to matched media. Configure them in the action section below the rule builder, which opens once Enable lifecycle action is switched on.

Available Actions

Every library type offers the same eight actions, against Radarr (movies), Sonarr (series) or Lidarr (music):

Action	Description
Do Nothing	Track matches without taking action (no *arr server needed unless it manages tags)
Delete from Radarr / Sonarr / Lidarr	Remove the whole movie, series or artist from the *arr app and delete its files. Optionally adds an import list exclusion so lists don’t add it back
Unmonitor & Delete Files	Unmonitor, then delete the matched files
Monitor & Delete Files	Delete the matched files and keep (or set) them monitored, so the *arr app grabs them again
Delete Files Only	Delete the matched files without changing monitoring
Unmonitor Only	Stop monitoring in the *arr app; nothing is deleted
Change Quality Profile	Switch the *arr item to a different quality profile
Search for New Copy	Trigger an *arr search for a new copy of the item

The three file-delete actions can Search for new copy after file deletion.

Manage Tags adds and removes *arr tags alongside the action, including Do Nothing. It has two lists, Add Tags and Remove Tags, and one action can use both — for example, add archived while removing new. A tag can be in only one of the lists: picking it in one takes it out of the other. Tags are added first, then removed, and the record is written once. Manage Tags is unavailable only with Delete from …, which removes the *arr record and its tags with it; the file-only deletes keep the record, so tags apply to them. Tags — added, removed or both — belong to the whole series or artist in Sonarr and Lidarr, so on a Series or Music rule set they can’t follow criteria that describe one episode or track, Season Number and the other episode fields included (see Actions on the whole show with series scope off).

Which files a file delete removes

Delete Files, Unmonitor & Delete Files and Monitor & Delete Files act only on the episodes or tracks that matched, never on the whole series or artist:

• Sonarr finds each matched episode by its season and episode number. If your media server’s air date for that episode is more than two days from Sonarr’s, the two number the show differently (common with absolute-ordered anime), and the episode is skipped. A file that holds several episodes (a double episode) is deleted only when every episode in it matched: otherwise it would also delete an episode that did not match, or one you protected with an exception. Search after searches the deleted episodes by id, and Monitor & Delete Files also monitors those episodes after the delete, since Sonarr can unmonitor episodes it deletes.
• Lidarr finds each matched track by its MusicBrainz track id, then by its disc and track number on the album of the same name, then by its exact title on that album. Anything ambiguous is skipped. A track is never matched to the same song on a different album.
• When none of the matched episodes or tracks can be found in the *arr app, the action is recorded as failed rather than completed. The deletion stats count only the files actually deleted.

On a music rule set evaluated per artist, the artist is every track in the library with that artist name, except when every track of that name carries a MusicBrainz artist id and they carry two or more different ones: then each id is its own artist, so two bands called “Nirvana” are evaluated, and deleted, separately. If any track of the name has no id, the name stays one artist, since an untagged track could belong to either and splitting it off would leave its plays out. Before Delete removes such an artist, Librariarr asks Lidarr about the other ids under the same name, and refuses if Lidarr says one of them is the same artist (an artist MusicBrainz has merged can appear under its old and new ids).

On a music rule set evaluated per track, an artist-level action (Delete, Unmonitor, Change Quality Profile, Search) runs once per artist, covering the artist’s matched tracks; file deletes stay per track. Copies of the same track on two servers count as one.

Change Quality Profile

This action switches a movie, series, or artist to a different quality profile in the linked *arr instance.

• The dropdown is populated live from the selected *arr instance’s quality profiles, so it always reflects what the *arr server currently offers.
• Items that are already on the selected profile are skipped at execution time. No update call is made and the action completes as a no-op.
• Combining this action with arrQualityProfile rule conditions lets you upgrade or downgrade items that don’t match your desired profile (for example: “any movie whose current quality profile is SD → switch to HD-1080p”).
• The target profile is required when the action is enabled — Save is disabled until one is selected.
• Toggle Search for upgrade after profile change to trigger an immediate *arr search after the profile is updated. The search only fires when the profile actually changed — skipped (no-op) items don’t trigger a search.

Search for New Copy

This action triggers an *arr search for a new copy of the matched movie, series, or artist without changing monitoring, quality profile, or deleting anything. It is a standalone alternative to the Search after / Search for upgrade toggles that accompany the delete-files and quality-profile actions — use it when all you want is to kick off a fresh search.

Configuring Actions

Each action links a rule set to an *arr instance:

1. Select the *arr server at the top of the editor (e.g., “My Radarr”) — the rule set’s *arr criteria are also read from this instance
2. Switch on Enable lifecycle action and choose the Action type
3. Set the Delay (days) — how long after a match the action runs (default 7)
4. Set action-specific options (import list exclusion, target quality profile, search after)
5. Optionally turn on Manage Tags to add tags, remove tags, or both

Caution

The Delete action permanently removes files from your *arr instance and, optionally, from disk. Preview your matches carefully before enabling deletion rules.

Note

Repeat scheduling. A non-destructive action (Unmonitor, Do Nothing, Search for New Copy, Change Quality Profile) leaves the item in your library, so it keeps matching the rule. To avoid re-running the same action every cycle, Librariarr won’t re-schedule an item that already has a completed action with an identical configuration. The comparison covers the whole action — its type, target quality profile, Arr instance, search-after toggle, and tag set — so you can re-configure a rule’s action without recreating the rule and it will fire again. For example, changing the action from Search for New Copy to Delete from Radarr, editing the tags an action applies, or pointing a Change Quality Profile action at a different profile all schedule the action again, because the new action has never run on that item. Completed Delete actions are always eligible to re-schedule, so a deleted title that is re-downloaded (or whose delete failed silently) is acted on again. With series scope off, a completed Unmonitor Only or Search for New Copy covers only the episodes it acted on: an episode of the same show that matches later (one watched since, under an “unmonitor watched episodes” rule) gets an action of its own, for just the new episodes. On a Series rule set this is tracked per episode, whichever episode the show’s match happens to be stored against, so an episode an earlier run covered is never acted on twice. A whole-series action (series scope on) waits while every episode it matches has been covered; when one it never covered starts matching — including after a switch from series scope off — the series action runs once more.

Tip

See Deletion Safety for an in-depth, layer-by-layer description of every check that stands between a rule firing and a file being deleted, including the exact source locations and tests that enforce each one.

Recycle Bin Safety Check

When you configure a destructive action (Delete, Delete Files, Unmonitor & Delete Files, Monitor & Delete Files) for an *arr instance, Librariarr queries that instance for its Recycle Bin Path (Settings → Media Management in Sonarr/Radarr/Lidarr).

• If a recycle bin path is set, deleted files are sent to that path before being permanently removed (per the configured cleanup days).
• If no path is set, deletes are immediate and unrecoverable.

When the recycle bin is disabled, Librariarr surfaces the risk in two places:

1. An inline amber warning appears under the Action type select.
2. On save, a confirmation modal blocks the save until you check “I understand that deletes will be permanent and unrecoverable.” The modal includes a deep link to the *arr instance’s Media Management settings so you can configure a recycle bin without leaving the page.

The acknowledgement is remembered per *arr instance for the current session — once you accept, you won’t be re-prompted for that same instance until the page is reloaded.

Plex Collections

A rule set can keep a Plex collection in sync with its matches — useful for surfacing a “Leaving Soon” shelf to your users. In the rule editor, turn on Sync matches to a Plex collection, then pick a collection from the dropdown or choose Create new collection….

Collections are reusable, saved definitions (Plex only). Each one owns its presentation settings:

• Collection name — the title shown in Plex.
• Sort name (optional) — a sort title prefix (e.g., !001) to pin the collection to the top of a library.
• Sort order — Alphabetical, Release date, or Action date.
• Display on home screens / Display in library recommended — Plex visibility toggles.

Because the settings live on the collection (not the rule), editing them from any rule applies to every rule synced to that collection.

Merging rules into one collection

Multiple rule sets can target the same collection. When they do, the collection’s membership is the union of all of their matches — Librariarr never lets two rules fight over the same collection. For example, separate “4K movies leaving soon” and “unwatched series leaving soon” rules can both feed a single Leaving Soon shelf (within the same library type).

A collection is scoped to one library type (Movies, Series, or Music), since a Plex collection lives inside a single library. To use the same name for both movies and series, create two collections.

Action-date ordering across rules

With Sort order: Action date, items are arranged soonest-scheduled-action first. When several rules feed the collection, the ordering pools the scheduled action dates of all of them, so the shelf is correctly interleaved regardless of which rule scheduled each item. (Items without a pending action are placed last.)

Lifecycle of a collection

• Disabling collection sync on a rule, or deleting the rule, simply detaches it — the collection is re-synced to the remaining rules’ matches. The Plex collection is removed only when it has no remaining members.
• The collection Librariarr writes to Plex is never read back in as a library item. Collections are containers, not media, so the library sync skips them — a “Leaving Soon” shelf can’t turn into a fake movie in your Movies list, and it can never be matched by a rule.
• Writing the collection does not trigger a library sync. Plex reports the write back as a change to the collection and to every item it tagged, and the real-time sync recognises that echo as Librariarr’s own and ignores it — so a detection run cannot cause an off-schedule full sync of the server.
• To delete a collection definition outright, select it in the dropdown and use the trash button. You can delete it from the last rule that uses it — doing so removes the collection from that rule and deletes it from Plex. The button is disabled (and the API refuses) only while other rules still reference it, so remove it from those first.

Troubleshooting: matches exist but the collection is empty

The Matches page reads directly from the database, but the Plex collection is populated by a separate sync step that pushes each matched item to Plex by its rating key. If a rule has matches yet the Plex collection shows 0 items, check System > Logs for a line like Failed to sync collection "…" for library … — it now names the exact Plex request, HTTP status, and Plex’s own error message so you can tell what was rejected. Common causes:

• The Plex server has no stored machine identifier. Collections are written using the server’s identifier, so a server added without it is skipped (you’ll see a … has no machineId warning). Re-add the server through the Plex picker to store it.
• Stale rating keys. If Plex regenerated its rating keys (a library rebuild, “Optimize database”, or removing and re-adding the section), the stored keys no longer resolve and Plex rejects the update. Run a full sync of that library so Librariarr relearns the current keys.
• The matched copy lives on a different (or non-Plex) server. A movie present on more than one server resolves to whichever copy was matched; only its own server’s library can hold it in a Plex collection.

As a safety measure, Librariarr will not empty or delete a collection when its rules matched items but none of them resolved to that Plex library — it leaves the collection intact, so a resolution problem never silently wipes a shelf. When the matched items belong to that library but couldn’t be resolved to Plex rating keys (stale series titles, for example), a warning is logged; when they simply live in another library or server — normal in multi-library setups — the skip is only visible in debug logs. A collection is only removed when its rules genuinely match nothing.

How Rules Are Evaluated

Rules are evaluated in two steps:

1. Step 1 — Local data: Rules based on your media’s own properties (resolution, play count, dates, file size, etc.) are evaluated first using your database — this is fast.

2. Step 2 — External data: Rules based on Sonarr, Radarr, Lidarr, or Seerr data (tags, quality profiles, monitored status, requests) require live lookups to those services, so they run after Step 1 narrows down the results.

Note

Rules using external data (Step 2) are slower because they query your integrations. Use local-data rules to narrow your matches first for best performance.

Series scope and aggregate fields

For Series rule sets, the Match against entire series toggle (series scope) controls the unit of evaluation:

• Series scope on — the rule is evaluated against the whole show, and an action applies to the entire series. Every episode is a member of the match.
• Series scope off — the rule is evaluated against individual episodes, then results are grouped by show. A member-scoped action (such as Delete Files Only) acts only on the episodes that matched. Unmonitor Only and Search for New Copy also act only on the matched episodes: Sonarr unmonitors or searches those episodes and leaves the rest of the show as it is. Delete from Sonarr, Change Quality Profile, Unmonitor & Delete Files and Monitor & Delete Files (which unmonitor or monitor the series) and tags are properties of the series in Sonarr and apply to the whole show — so they can’t follow per-episode criteria (see Actions on the whole show with series scope off).

With series scope on, a rule judges the whole show, and its action covers every episode. The show’s own values are the same whichever episode you look at: its name (Title and Artist / Series), Play Count (the total of every episode), File Size (the sum), Last Played (the latest play of any episode), Date Added (the earliest), Watched By User (anyone who watched an episode), Has External ID (the show’s ids, which every episode stores), the series-aggregate fields below and every *arr and Seerr field. Only these can be used with series scope on, and a show is checked once against them — together with Matched By Rule Set, Has Pending Action and Server Count, which each episode has its own of: with one of those, a show matches only when the rule holds for every episode (see below).

Criteria not allowed with series scope on

Criteria that describe one episode or its file can’t be used with series scope on: Resolution and every other video and audio field, Container, Duration, the stream fields (Audio Language, Subtitle Language, Stream Audio Codec, the track counts) and stream query groups, Year, Release Date (the episode’s own — the *arr Release Date and First Aired describe the series and stay available), Rating, Audience Rating, Rating Count, Album, the episode fields (Season Number, Episode Number, Seasons Behind Latest), and the metadata Librariarr stores per episode: Genre, Studio, Content Rating, Label, Country and Is Watchlisted. Judging a whole show by one of them lets a single episode decide for every other: Resolution = 4K matched a show with one 4K episode, and Delete from Sonarr then deleted every 1080p episode with it. The metadata fields are no different: an episode keeps its own genres (it takes the show’s only when it has none), its own studio and content rating on Jellyfin and Emby, its own labels on Plex, and its own favourite flag on Jellyfin and Emby (a new episode also reads as not on your Plex watchlist until the next full sync), so NOT Content Rating = TV-MA would match a show with one TV-14 episode. To act on episodes by their resolution, codec or genre, turn series scope off and use an action that acts only on the matched episodes: each episode is checked on its own, and a file delete acts only on the episodes that matched.

• In the editor these fields, and Stream Query, are offered disabled while series scope is on, with the reason on hover. Turning series scope on over rules that use one shows a warning naming them, with a Turn off series scope button — offered only when the action acts on the matched episodes alone; with Delete from Sonarr or another whole-show action the warning says to switch the action as well. Each such condition is marked too, and Save, Preview and Test Media stay off, the reason on hover, until you resolve it.
• Saving such a rule set is refused by the server as well as the editor, with the criteria named; so is turning series scope on over them. A rule set already in that state can still be turned off with its switch in the rule set list.
• A rule set saved before this rule, or restored from a backup that has one, is not evaluated: detection skips it and keeps its matches as they are. The reason shows in System Logs, in the Re-evaluate notification on the Matches page, as Preview and Test Media errors, and as a Needs edit chip (the reason on hover) in the rule set list. Its pending actions are held: they don’t run on schedule, from Execute or Execute All on the Pending page, from Retry or through the API, and the Pending page marks them Held with the reason. Edit the rule set to release them. Removing the criteria and choosing Save only keeps its matches and holds its actions until the next detection run re-checks them, as any change to the rules does (see Editing a rule set); actions whose item still matches then run as scheduled. Turning series scope off clears its matches and cancels its pending actions, as any change of scope does.

Actions on the whole show with series scope off

With series scope off each episode is checked on its own, so an action that acts on the whole show would let one matching episode decide for every other: Resolution = 4K with Delete from Sonarr deletes a show with a single 4K episode, and Play Count = 0 deletes a show with one unwatched episode, however much of the rest was watched yesterday. Those actions — Delete from Sonarr, Unmonitor & Delete Files, Monitor & Delete Files, Change Quality Profile, and any action with Arr tags — may follow only what every episode of a show answers alike: Artist / Series (the show’s name), Has External ID, the series-aggregate fields, and every *arr and Seerr field. Everything else is the episode’s own with series scope off, Title, Play Count, Last Played, Date Added, File Size, Watched By User, the cross-system fields and the episode fields included.

• In the editor, while the rules use such a criterion, those actions are offered disabled in the action picker, and Manage Tags with them, the reason on hover; and while one of them is chosen, the criteria it can’t follow are offered disabled in the builder. A rule set that has both anyway shows a warning naming them, with the ways out: remove the criteria, switch to an action that acts only on the matched episodes (Delete Files Only, Unmonitor Only or Search for New Copy, without tags), or — when the show itself answers every one of them, as it does Play Count (its total) — Turn on series scope.
• Saving it is refused, whether by the rules, a new action type, its tags, or switching the action on. A save that only turns the action off, or switches it to one on the matched episodes, is always allowed.
• Preview, Test Media and the Match Changes Preview judge the rules with the action as you have it in the editor, saved or not: while it can’t follow them, the buttons stay off with the reason on hover, and the server refuses each of them with the reason detection would give, rather than showing matches the rule set could never act on.
• A rule set saved before this rule is skipped by detection and its actions are held, exactly as above.
• On the Query page, which checks every episode on its own, the same actions are refused on the results of a query using such a criterion — and so, grouped by show, are Unmonitor Only and Search for New Copy, which act on the whole series there unless the query uses an episode field (see When a query action is refused).

Some fields are series-aggregate fields — availableEpisodeCount, watchedEpisodeCount, watchedEpisodePercentage, lastEpisodeAiredAt, lastEpisodeAddedAt, latestEpisodeViewDate, and seriesLastPlayedAt (Series Last Played). These describe the show as a whole and can only be computed across every episode, so a rule that references one is always evaluated at the series level — even with Series Scope off.

Series Last Played is the most recent play date across all episodes (the max of every episode’s last-played date). Use it to find shows nobody has touched in a while — e.g. Series Last Played is not in the last 365 days matches only series where every episode was last played over a year ago. This differs from the per-episode Last Played field with series scope off (which would match a series as long as it has any old episode, even if another episode was watched yesterday; with series scope on a show’s Last Played is already its latest play) and from Latest Episode View Date (the play date of the newest episode by number — “did they watch the latest episode?”).

Plays by other users count too

Play Count, Last Played and Series Last Played reflect plays by every user on your media server, not just the account Librariarr signs in as. They’re kept in step with the same watch history the History page shows, so if a rule ever disagrees with History for a title, run a sync.

Is Watchlisted is different: a Plex watchlist belongs to your Plex account, and Librariarr reads it during a full sync — so watchlist changes appear on the next full sync rather than instantly. Every item in the library is checked against the watchlist on that sync, whether or not its own metadata changed, so removing a title from your watchlist clears the flag just as adding one sets it. If the watchlist cannot be fetched in full (plex.tv unreachable, token expired, or its pages stopping before the total it reports), the stored flags are kept unchanged for that sync and the failure is logged, rather than every item missing from a partial answer being marked as not watchlisted. The watchlist is read in pages, so a watchlist of any size is read whole.

When Series Scope is off and your rule mixes an aggregate field with a per-episode field (for example, available episode count ≥ 20 and resolution = 4K), each episode is checked on its own, with the show’s aggregate values carried over to it. The show matches when at least one episode passes — whichever episode that is — and a member-scoped file delete acts only on the episodes that passed (here, just the 4K episodes), not every episode of the series. A show none of whose episodes passes on its own is not matched, even when the show as a whole would (a File Size only the whole show adds up to, say). Every field except the aggregates and the *arr and Seerr fields is the episode’s own here, exactly as without an aggregate field: Play Count is the episode’s plays, not the show’s total, and Matched By Rule Set is whether a rule set matched that episode. A rule reading only aggregate, *arr or Seerr fields is checked once per show and matches all of its episodes or none. With Series Scope on, the same rule can’t be saved: Resolution describes one episode.

Cross-system criteria in series and artist scope

Matched By Rule Set, Has Pending Action and Server Count belong to each episode, or each track: a rule set matched that episode, an action is pending on it, it is on so many servers. In series scope a show matches only when the rule holds for every episode, each read with its own value for these fields and the show’s own value for everything else — and in artist scope an artist, for every track. One episode never decides for the whole show:

• Matched By Rule Set = X matches a show only when X matched every one of its episodes (every episode a series match covers counts as matched), not a show X matched one episode of.
• Has Pending Action = true matches a show only when every episode has an action pending; Server Count ≥ 2 only one every episode of which is on two or more servers.
• The protective forms read as you would expect: NOT Matched By Rule Set = Keep excludes a show any of whose episodes the Keep rule set matched, in either scope, and Has Pending Action = false skips a show any episode of which another rule set has already scheduled (every episode a show or artist action acts on counts as pending, not only the one it is stored against).
• Mixed with a show-level criterion, the show’s own value is read for every episode: Matched By Rule Set = X or Play Count = 0 matches an unwatched show whatever X matched, and a watched one only when X matched every episode.

The matched criteria on the Matches page, in Preview and in Test Media follow the same reading: such a criterion is listed as matched only when it holds for every episode, and its value shows each episode’s own — one value when they all agree, otherwise each value with how many episodes have it (none (2 of 3); Keep (1 of 3)).

Has Pending Action also counts another server’s copy of an item an action is pending on — the copies a merged match lists, and the same title on another server — since every copy is backed by the one *arr record the action acts on; and it never counts the rule set’s own actions, so Has Pending Action = false does not cancel the action its own rule set scheduled on the previous run.

Season and episode criteria

Season Number, Episode Number and Seasons Behind Latest describe a single episode, so they need series scope off: a whole show has no season or episode number, and one episode’s must never decide for the whole show. They follow the same rules as every other criterion of one episode (see Criteria not allowed with series scope on and Actions on the whole show with series scope off): the editor disables them while series scope is on, a rule set saved with one in series scope is refused, and one already in that state (restored from a backup, say) is skipped by detection and its actions held until it is edited. With series scope off the show is matched through the episodes that satisfy the rule, and the actions on the matched episodes — Delete Files Only, Unmonitor Only, Search for New Copy and Do Nothing, without tags — act on exactly those episodes. An action on the whole series can’t follow them: Delete from Sonarr, Change Quality Profile, Unmonitor & Delete Files and Monitor & Delete Files (which unmonitor or monitor the whole series — Seasons Behind Latest ≥ 2 with Unmonitor & Delete Files would stop Sonarr downloading the two newest seasons too) and Arr tags are offered disabled and refused on save.

Seasons Behind Latest is measured by season number against the newest numbered season of the same show in the same library that has a file — the placeholder episodes Jellyfin and Emby can list for missing or announced episodes don’t count, so an announced season never pushes the seasons you have further back: with seasons 1–5 in the library, season 5 is 0 and season 1 is 4. A gap in numbering counts (seasons 1, 2 and 5 give season 2 a value of 3), and the value is re-measured on every run, so it follows the show as new seasons are added. Specials (season 0) and episodes without a season number have no value: they never match a comparison such as ≥ 2, and match Is Empty.

A rule that mixes these with a series-aggregate field (for example, watched episode % ≥ 90 and seasons behind latest ≥ 2) is checked episode by episode with the show’s aggregate values carried over, as described above: the show matches through the episodes that satisfy every condition, and those are the episodes its action acts on.

Artist scope

Music rule sets have the same switch, Match against entire artist. On, the rules are evaluated against each artist’s tracks taken together and an action covers the artist: only the artist’s own values (its name, play total, summed size, latest play, listeners and the Lidarr fields) can be used, and each artist is checked once against them — together with the cross-system fields, which each track has its own of: an artist matches only when the rule holds for every track (as in series scope).

As in series scope, criteria that describe one track or its file can’t be used with artist scope on: Audio Codec and every other audio and video field, Container, Duration, the stream fields and stream query groups, Year, Release Date, Rating, Audience Rating, Rating Count, Album, and the metadata stored per track — Genre, Studio, Content Rating, Label, Country, Is Watchlisted and Has External ID (a track carries its own recording id, and not every track carries its artist’s). One FLAC track would otherwise make Audio Codec = FLAC match the whole artist, and NOT Genre contains Rock match a rock band with one untagged track, and Delete from Lidarr remove every other album with it. The editor disables them, a save using one is refused, and a rule set already holding one is skipped by detection and its actions held until it is edited, exactly as with series scope. Off (track scope), the rules are evaluated per track, then grouped by artist, and every criterion is available to Delete Files Only (without Search after) and Do Nothing (without tags), which act on the matched tracks only. Every other Lidarr action acts on the whole artist — Delete from Lidarr, Unmonitor Only, Search for New Copy, Change Quality Profile, Unmonitor & Delete Files and Monitor & Delete Files (which unmonitor or monitor the artist), Search after a file delete (which searches the artist) and tags — and may follow only Artist / Series and the Lidarr fields, as with series scope off.

How series actions are named

A series match and its action are always named by the show. This holds on the Matches and Pending pages, in the action history, in System Logs and in Discord notifications. It is never named by the episode Librariarr stores the match against. An action that acts on exactly one episode is named by the show plus that episode’s season and episode number, for example Breaking Bad S03E10. That happens with a file delete whose rule matched a single episode, or a Query-page action on one episode. The history keeps that name after the episode has been deleted from your server.

Scheduling

Lifecycle processing runs on two independent schedules (configured in Settings → Scheduling):

• Detection: Evaluates rules and identifies matching media
• Execution: Performs configured actions on matched media

Both can be run manually via the Run Now button at any time.

Detection: incremental and full

Scheduled detection is incremental: it adds new matches, refreshes the ones it keeps, and removes matches whose items no longer satisfy the rules — cancelling their pending actions. Re-evaluate (per rule set) and Re-evaluate All on the Matches page run a full re-evaluation instead, replacing each rule set’s matches with exactly what its rules select now.

Turn on Sticky matches in a rule set to keep items matched after they stop meeting the rules: incremental runs then only add matches, and only a manual re-evaluation removes them. Turning it off holds the rule set’s pending actions until the next detection run drops what the rules no longer select (see Editing a rule set).

Action delay

When a match is found and the rule set’s action is enabled, an action is scheduled Delay (days) after detection (0–365, default 7) and appears on the Pending page until it runs. An item that already has a pending action is not scheduled again. When you change the delay, the editor offers to reschedule the actions already pending to the new delay from today.

Editing a rule set

Changing the rules prompts Save and re-detect (shows a Match Changes Preview — new, retained and removed — and Confirm and Save runs detection for the rule set at once) or Save only (the matches stay as they are until the next detection run re-checks them against the new rules). Until that run, the rule set’s pending actions are held: they don’t run on schedule, from Execute on the Pending page or through the API, even when due. The run that re-checks them keeps each action whose item still matches, with its date, and cancels the rest. Changing the rule set’s servers holds them the same way, and so do two saves that leave the rules as they are:

• Turning Sticky matches off. The matches the rules no longer select were kept only because the rule set was sticky; their pending actions wait for the next run, which removes those matches and cancels the actions.
• Enabling a disabled rule set again — in the editor or with its switch in the rule set list. Detection skips a disabled rule set, so its matches are as old as the day it was turned off; Execute All would act on them as they are.

In the editor both prompt Save and re-detect or Save only, as a change to the rules does. Action-only changes save directly and are copied onto the pending actions. Turning off Enabled or Enable lifecycle action cancels the pending actions.

A save also reaches whatever is already running for the rule set. A detection run that read the rule set before you saved — the scheduled one, say, still evaluating when Save and re-detect has finished — writes nothing and schedules nothing: its matches and actions are of the old rules, and it leaves them to the next run (System Logs says so; a Re-evaluate that lost its result that way lists the rule set as skipped). An execution under way — the scheduled one, or Execute All — acts on each item only while the rule set is still as it was when the execution read it, so a save mid-run stops it before the next item: the scheduled run leaves the rest pending for its next pass, and Execute All reports how many it executed and why it stopped (nothing at all ran: the request is refused). One item already with the *arr app when you save finishes.

On the Pending Actions page a held rule set’s group, and each of its pending and failed actions, carry a Held chip; hover it to see since when. Its Execute, Execute All and Retry buttons are turned off until the next detection run, and Execute All says how many actions it skips. To release them straight away, use the rule set’s Re-evaluate button on the Matches page. The page updates by itself when the detection run finishes.

A rule set that judges whole shows or artists on criteria describing one episode or track, or follows such criteria with an action on the whole show or artist with the scope off (saved before that was refused — see Criteria not allowed with series scope on and Actions on the whole show with series scope off), is held the same way, with that reason on its Held chip, until you edit it; Execute All then says its actions are held “until the rule set is edited”. A pending action is held too when its own action is such a one, even after the rule set’s action was changed (a backup restored over it, say).

Deletion Stats

The Pending Actions page displays a running total of data deleted by lifecycle actions — including the total bytes removed and the number of completed actions. This gives you visibility into how much storage the lifecycle system has reclaimed.

• Stats are computed from completed actions that have recorded file sizes
• Click the reset button to start counting from zero — historical action records are unaffected
• After a reset, only actions completed after the reset point are included in the totals

Limitations

• *arr actions require the corresponding integration to be configured and reachable
• Rules using integration data are slower and scale with the number of matches
• File size rules accept input in MB but are stored and compared in bytes
• Wildcard matching uses * (any characters) and ? (single character), not regex