lidarr-fixer

A Spring Shell CLI tool for managing and migrating a Lidarr music library. Built to solve a specific problem: bulk-migrating artist paths from one base directory to another, with QNAP NAS verification and MusicBrainz integration for adding missing artists.

Background & Motivation

This is an oddly specific application — built specifically for my setup: a QNAP NAS running Lidarr, with a music library that needed reorganizing from a flat structure into an /artists/ subdirectory.

The problem was twofold:

• Bulk path updates are painful in Lidarr. There's no built-in way to migrate 100+ artists from one base path to another without clicking through each one individually.
• The Lidarr metadata server was down. This meant adding new artists through the normal UI wasn't possible — but the folders already existed on disk. The only way through was directly via the API using MusicBrainz IDs.

If you happen to have a QNAP NAS, use Lidarr, and find yourself in the same situation — this might save you a few hours.

Tech Stack

• Java 21, Spring Boot 4.0.3, Spring Shell 4.0.1
• Apache HttpClient 5 (with SSL bypass for self-signed NAS certs)
• Jackson, Apache Commons Text (fuzzy matching)

Configuration

Configuration lives in application.yaml (and use configure shell command at runtime for auth settings):

fixer:
  lidarUrl: http://your-lidarr-host:8686
  qnapUrl: https://your-qnap-host
  oldBasePath: /data/media/music
  newBasePath: /data/media/music/artists
  fuzzyThreshold: 0.85
  contactEmail: your@email.com

Recommended Order of Operations

This is the order that was used to successfully migrate a 115-artist library:

1. Sync folders first — finds QNAP folders not yet in Lidarr and adds them:

lidarr-sync-folders -q 1 -m 1

2. Update paths — migrates all Lidarr artist paths from oldBasePath to newBasePath:

lidarr-update-paths

Note: Both commands default to dry-run mode. Pass -d false to apply changes.

---

Commands

All commands are in the lidarr group. Run help in the shell to see all available commands.

---

lidarr-list

Lists all artists currently in Lidarr with their ID and path.

shell:> lidarr-list

Output columns: Artist name, Lidarr ID, current path.

---

lidarr-profiles

Lists all quality and metadata profiles configured in Lidarr. Useful for finding profile IDs before running lidarr-sync-folders or lidarr-add.

shell:> lidarr-profiles

---

lidarr-mb-search

Searches MusicBrainz for an artist by name and displays results sorted by match score.

shell:> lidarr-mb-search -s "Rammstein"

Option	Short	Description
--search	-s	Artist name to search for (required)

Results show: name, disambiguation, country, score, and MBID.

---

lidarr-add

Searches MusicBrainz, lets you pick an artist, and adds them to Lidarr. Optionally checks whether the artist folder already exists on QNAP.

shell:> lidarr-add -s "Parkway Drive"
shell:> lidarr-add -s "Parkway Drive" -q 1 -m 1

Option	Short	Description
--search	-s	Artist name to search (required)
--default-quality-profile	-q	Quality profile ID (prompts if omitted)
--default-metadata-profile	-m	Metadata profile ID (prompts if omitted)

Flow:

1. Searches MusicBrainz, shows top 10 results
2. You select a result by number
3. Lidarr resolves the MBID
4. Profile selection (if not passed as options)
5. Shows proposed path and QNAP existence check
6. Confirm to add

---

lidarr-update-single

Previews and optionally applies a path update for a single artist by Lidarr ID. Useful for testing the update flow before running lidarr-update-paths on the full library. Defaults to dry-run mode for safety.

shell:> lidarr-update-single -i 42
shell:> lidarr-update-single -i 42 -d false

Option	Short	Description
--id	-i	Lidarr artist ID (required)
--dry-run	-d	Preview without applying (default: true)

Flow:

1. Fetches artist from Lidarr
2. Shows old path → proposed new path
3. Checks if new path exists on QNAP
4. If not found, attempts a fuzzy match against QNAP folders
5. If not dry-run, applies the update

---

lidarr-update-paths

Bulk-migrates all Lidarr artist paths from oldBasePath to newBasePath. Defaults to dry-run mode — pass -d false to apply changes.

shell:> lidarr-update-paths              # dry-run preview
shell:> lidarr-update-paths -d false     # apply changes
shell:> lidarr-update-paths -d false -s  # apply, skip QNAP verification

Option	Short	Description
--dry-run	-d	Preview changes without applying (default: true)
--skip-qnap	-s	Skip QNAP path verification (default: false)

Flow:

1. Loads all artists from Lidarr
2. Loads all folders from QNAP newBasePath
3. For each artist on oldBasePath:
   • [OK] — exact folder found on QNAP → updates immediately
   • [MISS] — not found → tries fuzzy match, prompts to accept/reject/enter custom path
   • [SKIP] — already on new path or unrelated path
4. Prints summary: Updated / Skipped / Failed

---

lidarr-sync-folders

Cross-references QNAP artist folders against Lidarr and interactively adds any that are missing. This is the inverse of lidarr-update-paths — it finds folders on disk that Lidarr doesn't know about. Fuzzy matching is enabled by default to avoid false positives from minor name differences.

shell:> lidarr-sync-folders -q 1 -m 1              # dry-run preview
shell:> lidarr-sync-folders -q 1 -m 1 -d true      # apply changes
shell:> lidarr-sync-folders -q 1 -m 1 -f false     # disable fuzzy filtering

Option	Short	Description
--dry-run	-d	Preview missing folders without adding (default: false)
--use-fuzzy	-f	Exclude near-matches from missing list using fuzzy threshold (default: true)
--default-quality-profile	-q	Quality profile ID (prompts if omitted)
--default-metadata-profile	-m	Metadata profile ID (prompts if omitted)

Flow:

1. Lists all folders in QNAP newBasePath
2. Lists all artist folder names from Lidarr
3. Computes folders missing from Lidarr (exact match, fuzzy-filtered by default)
4. Shows summary and missing list
5. For each missing folder:
   • Searches MusicBrainz using the folder name
   • Shows top 10 results
   • You select a result, or s to skip, or q to quit
   • Adds the artist to Lidarr using the QNAP folder name as the path
6. Prints summary: Added / Skipped

Tip: Fuzzy matching is on by default to avoid being prompted for artists already in Lidarr under a slightly different folder name (e.g. Die Antwoord vs die antwoord). Use -f false to see all unmatched folders regardless.

---

Notes

• The QNAP API requires paths without a leading slash and with literal / separators (no URL encoding).
• The Lidarr PUT endpoint requires the full artist object — only the path field is changed.
• MusicBrainz requires a valid User-Agent header in the format AppName/Version ( contact ). Requests without one will be rejected with 403.
• SSL certificate validation is bypassed for QNAP (self-signed cert). Lidarr uses a standard HTTP connection.