Settings Reference
This page documents every setting available in Nudgarr, grouped by tab. All settings are stored in /config/nudgarr-config.json and are also editable via the web UI.
Tab order: Instances · Overrides · Settings · CF Score · Filters · Sweep · History · Imports · Intel · Notifications · Advanced
Settings tab
Scheduler
| Setting | Default | Description |
|---|---|---|
| Automatic Sweeps | Off | Enables the cron-based scheduler. When off, sweeps only run when you press Run Now. |
| Cron Expression | 0 */6 * * * | A standard 5-field cron expression defining when sweeps fire. The field is validated on change — an amber glow indicates an invalid expression. See cron syntax below. |
| Container Time | (display only) | The current container local time, shown beneath the cron field so you can confirm your schedule at a glance. Controlled by the TZ environment variable. |
Note: Nudgarr does not sweep on startup. The first sweep fires when the cron expression next matches, or immediately if you press Run Now.
Maintenance Window
Scheduled sweeps can be suppressed during a defined time window each week. Manual Run Now is never affected -- suppression applies only to cron-triggered fires. Import checking continues during the window as it only contacts your local Radarr and Sonarr instances, not indexers.
| Setting | Default | Description |
|---|---|---|
| Enable Maintenance Window | Off | Toggle to activate the window. When off, all other maintenance window fields are greyed out and the window has no effect. |
| Start Time | (empty) | Time in 24-hour HH:MM format when the suppression window begins. |
| End Time | (empty) | Time in 24-hour HH:MM format when the suppression window ends. Overnight ranges are supported. |
| Days | (none) | Individual day-of-week pill toggles (Mon through Sun). The window only suppresses sweeps on the selected days. |
A hint line below the time inputs describes the active window once both times and at least one day are set.
Cooldown
| Setting | Default | Description |
|---|---|---|
| Cooldown (Hours) | 48 | How long Nudgarr waits before searching the same item again. Applies to all three pipelines. 0 disables cooldown entirely — items are eligible for searching every sweep. |
Cron syntax
Nudgarr uses standard 5-field cron: minute hour day-of-month month day-of-week
| Example | Meaning |
|---|---|
0 */6 * * * | Every 6 hours on the clock (default) |
0 * * * * | Every hour |
30 2 * * * | Daily at 02:30 container time |
*/30 * * * * | Every 30 minutes |
Use the TZ environment variable to make the schedule fire in your local timezone rather than UTC.
Cutoff Unmet
Controls the Cutoff Unmet pipeline independently for Radarr and Sonarr.
Radarr
| Setting | Default | Description |
|---|---|---|
| Radarr Cutoff Unmet | On | Enables the Cutoff Unmet pipeline for Radarr. When off, no Cutoff Unmet searches run for any Radarr instance. The toggle is the on/off switch — Max Per Instance has no effect when this is off. |
| Max (Per Instance) | 1 | Maximum Cutoff Unmet movies to nudge per Radarr instance per sweep. 0 means all eligible items are nudged each run — use with care on large libraries. |
| Sample Mode | Random | Controls which eligible Radarr items are picked each run. See Sample Mode below. |
Sonarr
| Setting | Default | Description |
|---|---|---|
| Sonarr Cutoff Unmet | On | Enables the Cutoff Unmet pipeline for Sonarr. When off, no Cutoff Unmet searches run for any Sonarr instance. |
| Max (Per Instance) | 1 | Maximum Cutoff Unmet episodes to nudge per Sonarr instance per sweep. 0 means all eligible items. |
| Sample Mode | Random | Controls which eligible Sonarr items are picked each run. |
Sample Mode
Applied independently to Radarr and Sonarr for the Cutoff Unmet pipeline. Backlog has its own independent Sample Mode setting in the Advanced tab.
| Mode | Behaviour |
|---|---|
| Random | Picks items in a random order each run (default) |
| Alphabetical | Picks items sorted A to Z by title |
| Oldest Added | Prioritises items added to your library first |
| Newest Added | Prioritises items added most recently |
| Round Robin | Picks whoever has been waiting longest since their last search. Items never searched go first in random order. |
Throttling
| Setting | Default | Description |
|---|---|---|
| Batch Size | 1 | Number of items sent in a single search API call. Increasing this reduces the number of API calls but may exceed indexer limits. |
| Sleep (seconds) | 5 | Fixed wait between batches during a sweep. |
| Jitter (seconds) | 2 | Random additional wait added on top of Sleep, up to this value. Helps avoid predictable API timing patterns. |
Advanced tab
The Advanced tab is split into two cards side by side.
Left card — Backlog Nudges and Auto-Exclusion
Backlog Nudges
Off by default. See Radarr & Sonarr Backlog for full details.
| Setting | Default | Description |
|---|---|---|
| Radarr Backlog | Off | Enables missing movie searches for Radarr instances |
| Radarr Missing Max | 1 | Max missing movies to nudge per sweep per instance. 0 means all eligible items. |
| Radarr Missing Added Days | 14 | Only search movies added at least this many days ago. 0 disables the age filter. |
| Radarr Backlog Sample Mode | Random | Pick order for missing Radarr items. Independent of the Cutoff Unmet Sample Mode. Options: Random, Alphabetical, Oldest Added, Newest Added, Round Robin. |
| Radarr Grace Period (Hours) | 0 | Wait this many hours after a missing item's availability date before the first search. 0 disables the grace period. |
| Sonarr Backlog | Off | Enables missing episode searches for Sonarr instances |
| Sonarr Missing Max | 1 | Max missing episodes to nudge per sweep per instance. 0 means all eligible items. |
| Sonarr Backlog Sample Mode | Random | Pick order for missing Sonarr items. Independent of the Cutoff Unmet Sample Mode. Options: Random, Alphabetical, Oldest Added, Newest Added, Round Robin. |
Note: Sonarr does not have a Missing Added Days filter or Grace Period — those settings are Radarr only.
Auto-Exclusion
| Setting | Default | Description |
|---|---|---|
| Auto-Exclude Movies After | 0 | Auto-exclude a movie after this many searches with no confirmed import. 0 disables auto-exclusion for Radarr entirely. |
| Unexclude Movies After (days) | 0 | Automatically remove a movie from auto-exclusions after this many days. 0 means excluded until manually removed. Only active when the threshold above is above 0. |
| Auto-Exclude Shows After | 0 | Auto-exclude a show after this many searches with no confirmed import. 0 disables auto-exclusion for Sonarr. |
| Unexclude Shows After (days) | 0 | Automatically remove a show from auto-exclusions after this many days. |
Right card — Pipelines, Data, Security, and Preferences
For the Arr-tists
| Setting | Default | Description |
|---|---|---|
| Per-Instance Overrides | Off | Enables per-instance override configuration. Adds an Overrides tab to the navigation. See Per-Instance Overrides. |
Pipelines
| Setting | Default | Description |
|---|---|---|
| CF Score Scan | Off | Enables the CF Score pipeline. Adds the CF Score tab to the navigation. See CF Score. |
Data Retention
| Setting | Default | Description |
|---|---|---|
| State Retention (days) | 180 | History and cooldown entries older than this are pruned on the next sweep. 0 disables pruning. |
Stats
| Setting | Default | Description |
|---|---|---|
| Import Check (minutes) | 120 | How often Nudgarr polls Radarr/Sonarr to confirm imports. Runs on its own independent timer. Also triggers the auto-exclusion evaluation after each cycle. |
Security
| Setting | Default | Description |
|---|---|---|
| Require Login | On | Requires login before accessing the UI. |
| Session Timeout (minutes) | 30 | Minutes of inactivity before requiring re-login. |
UI Preferences
| Setting | Default | Description |
|---|---|---|
| Onboarding | — | A Replay button that re-runs the first-run walkthrough. |
| Show Support Link | On | Controls whether the donate/support link appears in the header. |
Import check interval and auto-exclusion: Auto-exclusion evaluates titles at the end of each import check cycle, not during the sweep. If your import check interval is longer than your cron schedule, a title may accumulate extra searches before it is evaluated. To keep auto-exclusion responsive, set the import check interval equal to or shorter than your cron schedule.
If you forget your password, stop the container, delete
nudgarr-config.json, and restart — Nudgarr will re-run onboarding. You will need to re-enter all settings.
Support & Diagnostics
At the bottom left of the Advanced tab.
| Control | What it does |
|---|---|
| Backup All | Downloads a zip of your config and database |
| Log Level | Sets logging verbosity — DEBUG, INFO, WARNING, or ERROR. Takes effect immediately. |
| Download Diagnostic | Downloads a sanitised diagnostic report for filing issues |
| Open Issue | Opens the GitHub issues page |
Danger Zone
At the bottom right of the Advanced tab. All actions are irreversible.
| Button | What it does |
|---|---|
| Clear History | Deletes all search history entries. Cooldown records are removed — all items become immediately eligible for searching. Intel data is not affected. |
| Clear Imports | Deletes all confirmed import entries from the Imports tab. Lifetime Movies and Episodes totals are not affected. Intel data is not affected. |
| Clear Log | Truncates the active nudgarr.log to zero bytes. The log resumes writing immediately. |
| Reset Config | Resets all settings to factory defaults. Your history and database are preserved. |
Clear Exclusions is on the History tab, not in the Danger Zone. It offers three options: Clear Auto, Clear Manual, or Clear All.
Reset Intel is on the Intel tab directly, not in the Danger Zone.
Notifications tab
See Notifications (Apprise) for full setup instructions.
| Setting | Default | Description |
|---|---|---|
| Notifications Enabled | Off | Master toggle for all push notifications |
| Apprise URL | (empty) | One or more Apprise-format notification URLs |
| Notify on Sweep Complete | On | Send a notification after each sweep with a summary of searches and skips |
| Notify on Import | On | Send a notification when a confirmed import is detected |
| Notify on Auto-Exclusion | On | Send a notification when a title is auto-excluded |
| Notify on Error | On | Send a notification when a sweep or instance error occurs |