needlectl is a command-line client for
DroppedNeedle. It talks to DroppedNeedle over
its REST API (/api/v3) and manages the native library and playlists: importing
CSV playlists (such as a Spotify library export), relinking a playlist's
unplayable tracks to library files, and deleting albums or single tracks.
The import is idempotent and library-aware: tracks that already exist in your DroppedNeedle library are linked to their library file, and entries that were imported before the track was available are relinked once it appears.
- CSV playlist import with a tolerant parser (UTF-8/UTF-16 BOM, CRLF, quoted commas, case-insensitive and order-independent columns).
- Library-aware linking — each CSV row is matched against the DroppedNeedle native library (Unicode-normalized, exact then fuzzy title/artist/album).
- Idempotent — re-running an import never duplicates tracks. Duplicate rows in the CSV are preserved.
- Automatic refresh — previously unlinked entries whose track has since been added to the library are relinked in place.
- Source resolution — after importing,
resolve-sourcesis called so the server links tracks and records every available source. - Album deletion —
needlectl album deleteresolves an album by name (refusing ambiguous matches), cascades to all of its tracks, and moves the files to DroppedNeedle's recycle bin unless--keep-filesis given. - Track deletion —
needlectl track deleteresolves a single track by name (refusing ambiguous matches; same-named tracks on one album are shown with their disc/track number and picked with--track/--disc) and removes it, with the same--keep-fileschoice as album deletion. - Album rename —
needlectl album renamerenames an album through DroppedNeedle's staged tag-edit flow (stage a preview, verify it, then apply). The album field is album-scoped, so every track of the album is updated, and the rename is written into the audio files by the library management pipeline. - Track rename —
needlectl track renamedoes the same for a single track's title, which is track-scoped and leaves the rest of the album untouched. - Playlist relinking —
needlectl playlist relinkscans an existing playlist and links the entries that have no source yet to matching library files. Entries that already play are left untouched, so a working link is never replaced. - Cover repair —
needlectl playlist repair-coversre-links the artwork of entries whose stored cover URL is missing or points at the local album id instead of the album's MusicBrainz release group. - Missing-track acquisition —
needlectl playlist requestresolves the albums behind a playlist's unplayable tracks through DroppedNeedle's search and sends one request per recording by default (reading the album's MusicBrainz tracklist), or one album request with--albums. Anything that is not an exact title and artist match is reported, never guessed. - Track upload —
needlectl import uploaduploads audio files to DroppedNeedle's drop import and reports how the server identified each group; entries it could not identify are listed asneeds_review. - Held-entry resolution —
needlectl held listshows the downloads and uploads waiting for a decision (the "unmatched" files), andneedlectl held matchimports one as the MusicBrainz album you name; a release URL or MBID is resolved to its release group. logincommand that stores credentials in~/.needlectl.conf(written0600).- Clean, informative output with coloured progress and a summary;
--dry-runpreviews changes;--verboselists every decision. - No secrets on the command line — the password is never passed as a flag.
- mise (recommended) — manages the Go toolchain.
- A running DroppedNeedle instance reachable over HTTP(S).
- A DroppedNeedle account with permission to create playlists.
The Go version is pinned in mise.toml (go = "1.27"). If you prefer not to use
mise, install Go 1.27+ yourself and run the go commands directly.
git clone https://github.com/mimnix/needlectl.git
cd needlectl
mise install # installs the Go toolchain pinned in mise.toml
mise run build # produces ./bin/needlectlOptionally install it onto your PATH:
mise run install # go install .Or install a released version straight from GitHub:
go install github.com/mimnix/needlectl@latestReleases are cut from vX.Y.Z tags; pushing a tag runs
.github/workflows/release.yml, which:
- rejects tags that are not exactly
vX.Y.Z(no leading zeros, no suffix) or that do not point at a commit onmain; - runs
go vet, agofmtcheck and the test suite; - builds
linux,darwinandwindowsarchives foramd64andarm64, with the tag baked intoneedlectl --version; - publishes a GitHub release whose body is
docs/releases/<tag>.md, with the archives,SHA256SUMS, the release notes andCHANGELOG.mdattached.
Tagging a release:
# 1. move the Unreleased entries in CHANGELOG.md into ## [X.Y.Z]
# 2. write docs/releases/vX.Y.Z.md from docs/releases/TEMPLATE.md
git add -A && git commit -m "chore: release vX.Y.Z"
git push origin main
git tag -a vX.Y.Z -m "needlectl vX.Y.Z"
git push origin vX.Y.ZThe full checklist and the validation rules are in
docs/releases/README.md; the complete history is in
CHANGELOG.md.
# 1. Store the connection settings (prompts for server, username, password).
./bin/needlectl login
# 2. Preview what the playlist import would do (no changes are made).
./bin/needlectl playlist import "My Spotify Library.csv" --dry-run
# 3. Import for real.
./bin/needlectl playlist import "My Spotify Library.csv" --name AnimePrompts for the server URL, username and password, verifies the credentials
against the instance, and writes ~/.needlectl.conf with 0600 permissions.
$ needlectl login
Server URL [http://localhost:8688]: https://music.example.com
Username: admin
Password:
✓ Signed in as Admin (admin)
✓ Saved configuration to /home/you/.needlectl.conf
Flags:
| Flag | Description |
|---|---|
--server string |
Server URL; skips the prompt (global flag). |
--username string |
Username; skips the prompt. |
--skip-verify |
Save the settings without checking them against the server. |
If there is no interactive terminal (for example in CI), provide
--server/--username and set NEEDLECTL_PASSWORD.
Imports the CSV into a DroppedNeedle playlist. The playlist is found by name and created if it does not exist; the name defaults to the CSV file name without its extension.
$ needlectl playlist import "My Spotify Library.csv" --name Anime
› Reading My Spotify Library.csv
73 tracks, 0 warning(s)
› Authenticating with https://music.example.com
✓ Signed in as Admin (admin)
› Loading DroppedNeedle library
1204 tracks indexed
› Resolving playlist "Anime"
✓ Created playlist "Anime"
› Planning import
73 rows · 68 matched in library · 5 missing
to add 73 · to refresh 0 · unchanged 0
› Adding 73 tracks (68 linked, 5 unlinked)
✓ Added 73 tracks
› Resolving track sources
✓ Import complete
playlist: Anime
id: 4f1c…
library: 1204 tracks
added: 73 (68 linked)
refreshed: 0
unchanged: 0
playable: 68
unlinked: 5
Flags:
| Flag | Default | Description |
|---|---|---|
--name string |
CSV basename | Target playlist name. |
--dry-run |
false |
Show what would change without modifying anything. |
--resolve |
true |
Resolve sources after importing (links tracks now available). |
--batch-size int |
100 |
Number of tracks sent per add request. |
Global flags (available on every command):
| Flag | Description |
|---|---|
--config string |
Config file to use (default ~/.needlectl.conf). |
--server string |
Override the server URL from the config. |
--insecure |
Skip TLS certificate verification. |
-v, --verbose |
Print every decision while running. |
--no-color |
Disable coloured output (NO_COLOR is also honoured). |
--version |
Print the version. |
Uploads audio files to DroppedNeedle's drop import and waits for identification. DroppedNeedle always identifies the files itself: it groups them into album-shaped items and reports how each one ended up.
$ needlectl import upload ~/Downloads/"DOUBLE-DEAL (Live) - T.M.Revolution.mp3"
› Uploading 1 file to https://music.example.com
✓ Uploaded as job 461dafd3 from DOUBLE-DEAL (Live) - T.M.Revolution.mp3
› Waiting for DroppedNeedle to identify the files
item 15 imported T.M.R. LIVE REVOLUTION'15 -Strikes Back XI- · T.M.Revolution (1/1 files)
An item the server could not identify is reported as needs_review.
DroppedNeedle v3 removed the API for resolving those entries, so they have to
be decided in its web UI; the command prints a warning naming them.
Directories are walked recursively; hidden files and directories are skipped.
Flags:
| Flag | Default | Description |
|---|---|---|
--wait |
true |
Wait for identification to finish before reporting. |
--timeout duration |
5m |
How long to wait for identification. |
--dry-run |
false |
Show what would be uploaded without doing it. |
Lists the drop import batches of the signed-in user together with their entries.
DroppedNeedle v3 has no single-job endpoint, so the list is read from
GET /api/v3/import/jobs, which already carries every item.
$ needlectl import list --status needs_review
job: 461dafd3
uploaded: DOUBLE-DEAL (Live) - T.M.Revolution.mp3
item 15 needs_review Loose tracks (0/1 files)
Couldn't work out which album this is. Decide it in the web UI.
✓ 1 job, 1 entry
Flags:
| Flag | Default | Description |
|---|---|---|
--all |
false |
List the batches of every user instead of only yours. |
--status string |
– | Only show entries with this status (for example needs_review). |
Deletes an album from the library and cascades to all of its tracks. This is
a destructive, admin-only operation, so the album is always displayed and must be
confirmed interactively unless --yes is passed.
$ needlectl album delete "Elza" --artist "神崎エルザ"
› Authenticating with https://music.example.com
✓ Signed in as Admin (admin)
› Looking up album "Elza" in the library
album: Elza — 神崎エルザ
id: 9c2b…
tracks: 12
details: FLAC · 2018
! this removes the album and its 12 tracks, and moves their files to the recycle bin
Delete Elza — 神崎エルザ? [y/N]: y
› Deleting album Elza — 神崎エルザ
✓ Album deleted
album: Elza — 神崎エルザ
tracks: 12
files: move to the recycle bin
wanted: stop future downloads
The album is looked up by name and must match exactly one library album. If
several albums match, the candidates are listed and nothing is deleted — narrow
the search with --artist, or pass the exact id with --id. Use --dry-run to
see what would happen without deleting anything.
Flags:
| Flag | Default | Description |
|---|---|---|
--id |
false |
Treat the argument as an exact album id and skip the lookup. |
--artist string |
Restrict the lookup to this artist. | |
--keep-files |
false |
Only remove the album from the catalog; keep the files on disk. |
--keep-wanted |
false |
Keep the album queued for future automatic downloads. |
-y, --yes |
false |
Do not ask for confirmation (required in non-interactive sessions). |
--dry-run |
false |
Show what would be deleted without deleting anything. |
Warning: by default the audio files are moved to DroppedNeedle's recycle bin. Pass
--keep-filesto remove only the catalog entry, and--dry-runto preview.
Renames an album in the library. The album field is album-scoped, so this renames it for every track that belongs to the album — there is no per-track variant of this operation.
DroppedNeedle stages metadata edits rather than applying them directly, and
needlectl follows that flow: it reads the tag editor, stages a tag edit
preview, checks that the preview is ready, and only then applies it. Applying
writes the new name through the library management pipeline, which rewrites the
album's audio file tags in the background.
$ needlectl album rename "Elza" "Elza (Deluxe)" --artist "神崎エルザ"
› Authenticating with https://music.example.com
✓ Signed in as Admin (admin)
› Looking up album "Elza" in the library
› Reading the tag editor for Elza — 神崎エルザ
› Staging the rename "Elza" → "Elza (Deluxe)" (save-override)
album: Elza — 神崎エルザ
id: 9c2b…
from: Elza
to: Elza (Deluxe)
mode: save-override
preview: 4f8c…
! applying this writes the new name into the tags of all 12 tracks of this album
Rename "Elza" to "Elza (Deluxe)"? [y/N]: y
✓ Rename queued
album: Elza
from: Elza
to: Elza (Deluxe)
mode: save-override
operation: op_01H…
the library management pipeline applies this in the background
Flags:
| Flag | Default | Description |
|---|---|---|
--id |
false |
Treat the first argument as an exact album id and skip the lookup. |
--artist string |
Restrict the album lookup to this artist. | |
--mode string |
save-override |
save-override stores a local override that future management runs keep; write-once writes the value once and a later authoritative run may replace it. |
-y, --yes |
false |
Do not ask for confirmation (required in non-interactive sessions). |
--dry-run |
false |
Stage and validate the preview, then discard it without applying. |
This writes to your audio files. The rename is not a database-only change: it is published through DroppedNeedle's file organization, which rewrites the tags of the album's tracks. That is why the change is always confirmed and why
--dry-runstages a real preview before discarding it.
If the new name equals the current one the command is a no-op. If the album's identity has not been accepted yet, the command refuses before staging anything and names the album's identity state, identification status and review — those have to be resolved in DroppedNeedle first. If the staged preview comes back stale, expired or not ready, nothing is applied and the reason is reported.
Deletes a single track from the library. The track is looked up by name and must
match exactly one library track; use --artist and/or --album to narrow
the search, --track/--disc to pick between tracks that share a name on one
album, or --id for an exact track id.
$ needlectl track delete "Rising Hope" --artist "LiSA"
› Authenticating with https://music.example.com
✓ Signed in as Admin (admin)
› Looking up track "Rising Hope" in the library
track: Rising Hope — LiSA
id: 5a1e…
album: Launcher
position: track 1
details: MP3 · 4:20
! this removes the track and moves its file to the recycle bin
Delete Rising Hope — LiSA? [y/N]: y
› Deleting track Rising Hope — LiSA
✓ Track deleted
track: Rising Hope — LiSA
removed: 1
file: move to the recycle bin
--artist and --album cannot tell two same-named tracks on one album apart, so
when the matches all sit on the same album the command refuses and lists them
with their disc/track number, format and duration. Nothing is deleted until you
point at one:
$ needlectl track delete "Intro" --album "Launcher"
› Looking up track "Intro" in the library
! "Intro" matches 2 tracks:
entry-1 Intro — LiSA (Launcher) · track 3 · FLAC · 3:35
entry-2 Intro — LiSA (Launcher) · track 7 · FLAC · 3:41
needlectl: refusing to guess: these matches share the album — re-run with --track (and --disc if the number repeats across discs), or pass --id
$ needlectl track delete "Intro" --album "Launcher" --track 7
› Looking up track "Intro" in the library
track: Intro — LiSA
id: entry-2
album: Launcher
position: track 7
details: FLAC · 3:41
For a multi-disc album, add --disc as well. If two rows share a name and a
disc/track number they are indistinguishable, and only --id can select one.
Flags:
| Flag | Default | Description |
|---|---|---|
--id |
false |
Treat the argument as an exact track id and skip the lookup. Cannot be combined with the narrowing flags below. |
--artist string |
Restrict the lookup to this artist. | |
--album string |
Restrict the lookup to this album. | |
--track int |
0 |
Restrict the lookup to this track number. |
--disc int |
0 |
Restrict the lookup to this disc number. |
--keep-files |
false |
Only remove the track from the catalog; keep the file on disk. |
-y, --yes |
false |
Do not ask for confirmation (required in non-interactive sessions). |
--dry-run |
false |
Show what would be deleted without deleting anything. |
Warning: by default the track's file is moved to DroppedNeedle's recycle bin. Pass
--keep-filesto remove only the catalog entry; the file then stays on disk.
Renames a single track in the library. Only the track's title changes: the
title field is track-scoped, so the rest of the album is untouched — use
album rename to rename the album itself.
The track is looked up by name and must match exactly one library track; use
--artist, --album, --track and/or --disc to narrow the search, or --id
for an exact track id.
It follows the same staged flow as album rename: the tag editor is read, a
preview is staged and checked, and only then is it applied. Applying writes the
new title into the track's audio file tags through the library management
pipeline, so the change is confirmed interactively unless --yes is given.
$ needlectl track rename "Disorder" "Disorder (Live)" --artist "神崎エルザ"
› Authenticating with https://music.example.com
✓ Signed in as Mimmo (admin)
› Looking up track "Disorder" in the library
› Reading the tag editor for track Disorder — 神崎エルザ
› Staging the rename "Disorder" → "Disorder (Live)" (save-override)
track: Disorder — 神崎エルザ
id: t-1
from: Disorder
to: Disorder (Live)
mode: save-override
preview: job-1
! applying this writes the new title into the tags of this track's audio file
Rename "Disorder" to "Disorder (Live)"? [y/N]: y
✓ Rename queued
track: Disorder — 神崎エルザ
id: t-1
from: Disorder
to: Disorder (Live)
mode: save-override
operation: op_01H…
the library management pipeline applies this in the background
Flags:
| Flag | Default | Description |
|---|---|---|
--id |
false |
Treat the first argument as an exact track id and skip the library lookup. Cannot be combined with the narrowing flags below. |
--artist string |
Restrict the track lookup to this artist. | |
--album string |
Restrict the track lookup to this album. | |
--track int |
0 |
Restrict the track lookup to this track number. |
--disc int |
0 |
Restrict the track lookup to this disc number. |
--mode string |
save-override |
save-override stores a local override that future management runs keep; write-once writes the value once and a later authoritative run may replace it. |
-y, --yes |
false |
Do not ask for confirmation (required in non-interactive sessions). |
--dry-run |
false |
Stage and validate the preview, then discard it without applying. |
If the new title equals the current one the command is a no-op. The album's
MusicBrainz identity must already be accepted — the same gate as album rename —
and the refusal names the album state and review to resolve.
Scans the tracks of an existing playlist and links the ones that cannot be played yet to files of the native DroppedNeedle library. This is useful when a playlist was imported before its tracks were available, or when a library scan brought in files that were missing earlier.
Only entries with no source at all (library_file_id, track_source_id and
source_type all empty) are considered. Entries that already play — through the
local library, Navidrome, Plex or Jellyfin — are counted but never modified.
$ needlectl playlist relink Anime
› Authenticating with https://music.example.com
✓ Signed in as Admin (admin)
› Loading DroppedNeedle library
1024 tracks indexed
› Resolving playlist "Anime"
› Planning relink
120 entries · 65 already playable · 40 to relink · 15 unmatched
~ Disorder — 神崎エルザ
~ Rising Hope — LiSA
~ Gurenge — LiSA
… and 37 more (use --verbose to list them all)
› Linking 40 tracks to the library
✓ Relinked 40 tracks
› Resolving track sources
✓ Relink complete
playlist: Anime
id: pl_01H…
library: 1024 tracks
tracks: 120
playable: 65
relinked: 40
unmatched: 15
playable now: 105
unlinked: 15
The plan lists every entry that is about to be relinked, so you can review it
before anything changes (--dry-run stops right after this point). The list is
capped at 20 lines; --verbose lists them all and appends the library file each
entry matched:
› Planning relink
120 entries · 65 already playable · 40 to relink · 15 unmatched
~ Disorder — 神崎エルザ → 5a1e… · Elza · FLAC
~ Rising Hope — LiSA → 9c4b… · Launcher · MP3
…
How an entry is matched and linked: candidates are chosen by
title/artist/album (Unicode-normalized: exact title+artist+album, then exact
title+artist, then a fuzzy pass), but the link itself is always written with the
library file id of the match (track_source_id = that file id, with
source_type: local). Titles are never used to write the link, which is why the
--verbose output shows the resolved file id — a fuzzy title match is visible
there instead of being silent.
Linked entries also carry the album's cover art. DroppedNeedle stores the
artwork reference on the playlist row itself and never derives one from the
library file, so an entry created without it shows no cover — and the playlist's
own cover is assembled from those same per-track references. needlectl sets
cover_url to /api/v3/covers/release-group/<release group mbid>?size=250 from
the matched library track's release_group_mbid, so imported and relinked tracks
get artwork. cover_available is deliberately not a gate: it reports locally
scanned art, while the covers route also fetches art for the release group.
Entries with a missing or wrong URL can be fixed with playlist repair-covers.
Flags:
| Flag | Default | Description |
|---|---|---|
--id |
false |
Treat the argument as an exact playlist id instead of a name. |
--resolve |
true |
Also ask the server to resolve sources after relinking. |
--dry-run |
false |
Show what would be relinked without modifying the playlist. |
Why entries are replaced, not patched: the API's track update endpoint only accepts
source_typeandavailable_sourcesand resolves a file from the album metadata already stored on the entry. Spotify-imported entries usually have no MusicBrainz album id, so they cannot be patched.needlectltherefore inserts the linked entry at the same position and removes the old entry right after (insert first, so a failure can never leave a hole), which preserves the playlist order.
--resolvecomplements the local matching:resolve-sourcesgroups entries by MusicBrainz album id and links them to local/Navidrome/Plex/Jellyfin sources, catching tracks whose title our matcher cannot align. It cannot help entries that have no album id.
Lists the downloads and uploads DroppedNeedle kept out of the library because it could not accept an album for them — the "unmatched" files. Nothing is lost: the files stay on disk, and every entry records why it was held.
$ needlectl held list
› Authenticating with https://music.example.com
✓ Signed in as Admin (admin)
› Loading held entries
entry: 1
album: Strike — Far Out
state: held · weak_match
files: 1
guess: 6b2b962f-b2fc-40ac-b418-b1fa161b96cc
110. Far Out - Strike.mp3 · mp3 · 3:11 · track 110
from soulseek · release ae891a44-138f-4076-b4af-fe29af2f1a5a
The files do not match the album closely enough to import them safely.
✓ 1 entry waiting for a decision
link one with: needlectl held match <entry-id> <musicbrainz release or release-group URL/MBID>
guess is the release group DroppedNeedle tried, not a decision. Use the entry
id with held match to accept a different release.
Flags:
| Flag | Default | Description |
|---|---|---|
--all |
false |
Admins: list every user's entries instead of only yours. |
Imports one held entry as the MusicBrainz album you name. This is the manual decision the web UI offers on a held entry: the files are paired with the album's tracks and go into the library, without the automatic check that refused them.
DroppedNeedle links held files by release group, so the reference accepts a release URL, a release-group URL or a bare MBID. A release (or a bare MBID whose entity is unknown) is resolved to its group with a lookup on musicbrainz.org.
$ needlectl held match 1 https://musicbrainz.org/release/ae891a44-138f-4076-b4af-fe29af2f1a5a
…
› Resolving https://musicbrainz.org/release/ae891a44-… in MusicBrainz
✓ Resolved to release group 6b2b962f-b2fc-40ac-b418-b1fa161b96cc
release: 6b2b962f-b2fc-40ac-b418-b1fa161b96cc
files: 1
! this imports the entry's 1 file into the library as release group 6b2b962f-…
Import held entry 1? [y/N]: y
› Importing held entry 1 as release group 6b2b962f-…
✓ Held entry 1 resolved
imported: 1
Matching imports the files; it downloads nothing. Files the server cannot pair
with the album stay held and are reported as still held.
Flags:
| Flag | Default | Description |
|---|---|---|
--yes |
false |
Do not ask for confirmation (required when stdin is not a terminal). |
--dry-run |
false |
Resolve the reference and show what would be imported without importing it. |
Repairs the album artwork shown on a playlist's tracks.
DroppedNeedle stores a cover URL on every playlist entry and never derives one from the linked library file. Entries added while the album had no artwork, or linked with an older needlectl that used the local album id, keep showing no cover even after the art arrives. This command compares each linked entry with its album's MusicBrainz release group and stores the correct artwork URL.
The API cannot patch cover_url (only source_type and available_sources are
writable), so an entry that needs repair is re-added at its position and the old
one removed. Playlist order is preserved; only entries linked to the local
library are touched.
$ needlectl playlist repair-covers Anime --dry-run
› Authenticating with https://music.example.com
✓ Signed in as Admin (admin)
› Loading DroppedNeedle library
1582 tracks indexed
› Checking covers of "Anime"
66 entries · 42 to repair · 24 already right · 0 not in the library · 0 without a release group
~ Disorder — 神崎エルザ
~ Rising Hope — LiSA
…
✓ Dry run complete — no changes were made
playlist: Anime
tracks: 66
to repair: 42
unchanged: 24
Run it without --dry-run to apply the repairs. --all-playlists repairs every playlist
you own and prints one line per playlist.
Flags:
| Flag | Default | Description |
|---|---|---|
--id |
false |
Treat the argument as an exact playlist id instead of a name. |
--all-playlists |
false |
Repair every playlist you own. Cannot be combined with a playlist argument. |
--dry-run |
false |
Show what would be repaired without modifying any playlist. |
Requests the missing tracks of a playlist.
Playlist rows usually carry no MusicBrainz ids, so each unplayable entry is grouped by artist and album and the album is resolved through DroppedNeedle's MusicBrainz-backed search. Only an exact album title and artist match is used.
Two modes:
- Per track (default) — the album's MusicBrainz tracklist is read
(
release-group → releases → recordings) and the entry's title is matched to a recording, then onePOST /requests/tracksis sent. This fetches only that recording. --albums— onePOST /requests/albumsis sent for the release group. Use it when the whole album is wanted, or when a track title does not match the tracklist.
Curators get each download dispatched at once; other users get requests that wait for approval. Albums already requested are skipped in both modes.
Run playlist relink first: entries whose track is already in the library are
linked instead of downloaded.
$ needlectl playlist request "Classic Rock" --dry-run
› Authenticating with https://music.example.com
✓ Signed in as Admin (admin)
› Checking the albums of "Classic Rock"
71 entries · 71 not playable · 33 albums · per track
→ Quadrophenia — The Who: 1/1 tracks to request
→ Black Ice — AC/DC: 15/15 tracks to request
~ The Razors Edge — AC/DC: 10/11 tracks to request · 1 unmatched
✗ Duetos — Simone & Simaria: 0/3 tracks to request · 3 unmatched · no exact album and artist match
✓ Dry run complete — nothing was requested
playlist: Classic Rock
mode: per track
tracks: 71
not playable: 71
albums: 33
to request: 46
unmatched: 25 tracks
covered: 46 tracks
With --albums, to request counts albums and the report line shows the server
status (queued, awaiting_approval, already requested).
Flags:
| Flag | Default | Description |
|---|---|---|
--id |
false |
Treat the argument as an exact playlist id instead of a name. |
--albums |
false |
Request each album once instead of one recording per missing track. |
--dry-run |
false |
Resolve the tracks and show what would be requested without requesting it. |
The parser accepts the Spotify "library" export format and similar files. The first row must be a header; columns are matched by name, case-insensitively and in any order. Unknown columns are ignored.
| Column (any alias) | Required | Notes |
|---|---|---|
Track name, Title, Track, Song, Name |
yes | |
Artist name, Artist, Artists |
yes | |
Album, Album name |
no | Used to disambiguate matches. |
Track number, Track_number, Track no |
no | 3/12 is accepted (the part before /). |
Disc number, Disc_number, Disc |
no | |
Duration (ms), duration_ms, Duration |
no | Stored on unlinked entries. |
Playlist name, Playlist |
no | Parsed, currently unused. |
ISRC |
no | Parsed, currently unused. |
Spotify - id, Spotify id |
no | Parsed, currently unused. |
Rows without a track or artist are skipped with a warning; a file without a track or artist column is rejected. UTF-8 (with or without BOM), UTF-16 LE/BE, CRLF line endings and quoted fields containing commas are all supported.
Example:
Track name,Artist name,Album,Track number,Duration (ms)
"Disorder","神崎エルザ","Elza",1,215000
"Hello, World","Café Artist","Album, Two",2,198000- Read the CSV and normalise the rows.
- Authenticate with the credentials from
~/.needlectl.conf. - Load the library (
GET /api/v3/library/tracks, cursor-paginated) and build a match index. - Resolve the playlist by name, creating it if needed.
- Build a plan (a pure diff, no side effects) between the CSV rows and the playlist's current entries.
- Add new entries. A row matched to the library is added with
source_type: "local"andtrack_source_id: <library file id>, which makes DroppedNeedle setlibrary_file_id— the real link. Unmatched rows are added unlinked. - Refresh existing unlinked entries that now match the library: the linked replacement is inserted first, then the old entry is removed (so a failure leaves a duplicate, never a hole).
- Resolve sources (
POST /playlists/{id}/resolve-sources) so the server links any remaining available sources.
Normalize lowercases, applies Unicode NFC normalisation, and collapses every
non-alphanumeric rune to a single space. A row matches a library track when:
- the normalized
title + artist + albummatches exactly, or - the normalized
title + artistmatches exactly, or - a fuzzy score is high enough — title similarity must be ≥ 0.70 and the weighted score (55% title, 30% artist, 15% album; 65/35 without album) must be ≥ 0.80.
Ties are broken deterministically by library file id, so repeated runs make the same decisions.
The plan is a multiset comparison, not a set comparison: it counts how many
copies of each (title, artist, album) key exist in the playlist and adds only
the deficit. Re-running an unchanged import reports added 0 and the previous
unchanged count.
~/.needlectl.conf uses a minimal key = value syntax; values may be quoted,
blank lines and #/; comments are ignored, and unknown keys are preserved for
forward compatibility.
# needlectl configuration file.
server = "https://music.example.com"
username = "admin"
password = "secret"
insecure_skip_verify = falseThe file stores your password, so it is written with 0600 permissions.
needlectl warns if it finds a file with looser permissions.
Environment variables override the file, which is useful for CI:
| Variable | Overrides |
|---|---|
NEEDLECTL_SERVER |
server |
NEEDLECTL_USERNAME |
username |
NEEDLECTL_PASSWORD |
password |
NEEDLECTL_INSECURE_SKIP_VERIFY |
insecure_skip_verify |
A missing scheme defaults to https, except for loopback hosts (localhost,
127.0.0.1, ::1) where http is assumed. Only http and https are
accepted; embedded credentials (https://user:pass@host) are rejected. To use
plain HTTP on a remote host you must write the scheme explicitly:
server = "http://192.168.1.20:8688"Endpoints used, all under /api/v3:
| Method & path | Purpose |
|---|---|
POST /auth/login |
{username, password, transport:"bearer"} → {token, user} (tokens are only issued in bearer mode) |
GET /me |
Verify the session |
GET /library/tracks?q=&limit=&after= |
Native library listing / track search (cursor-paged, max 200 per page) |
GET /playlists |
List playlists |
POST /playlists |
{name} → create a playlist |
GET /playlists/{id} |
Playlist with tracks |
POST /playlists/{id}/tracks |
{tracks, position?} → add entries |
POST /playlists/{id}/tracks/remove |
{track_ids} → remove entries |
POST /playlists/{id}/resolve-sources |
Link/heal track sources (used by playlist relink --resolve) |
PATCH /playlists/{id}/tracks/{id} |
Update source_type/available_sources only (cannot set a library file) |
GET /library/albums?q=&limit=&after= |
Search the library albums (cursor-paged) |
GET /library/albums/{id} |
Album detail, including the row/listing revisions deletes need |
DELETE /library/albums/{id}?expected_revision=&expected_listing_revision=&delete_files=&stop_wanted= |
Remove an album and cascade its tracks |
DELETE /library/tracks/{id}?expected_revision=&delete_file= |
Remove a single track; delete_file=false keeps the file on disk |
GET /library/albums/{id}/tracks?limit=&offset= |
Album track list (used to open the tag editor) |
GET /library/management/tracks/{id}/tag-editor |
Editable metadata fields, scopes and revisions |
POST /library/management/tag-edit-previews |
Stage a metadata edit (local_track_id, mode, fields, expected_settings_revision, expected_policy_revision, idempotency_key) |
GET /library/management/previews/{id} |
Staged preview state (ready_for_confirmation, operation_row_revision) |
POST /library/management/previews/{id}/apply |
Apply a preview (preview_token, expected_operation_row_revision, idempotency_key, confirmation) |
POST /library/management/previews/{id}/discard |
Abandon a staged preview (expected_operation_row_revision) |
POST /import/uploads |
Multipart files → drop import job (the server identifies the files itself) |
GET /import/jobs?all= |
Import jobs with their entries (the client filters by id) |
GET /held?all= |
Entries waiting for a decision (the unmatched downloads/uploads) |
POST /held/{id}/match |
{release_group_mbid} → import an entry's held files as that album |
GET /search/albums?q=&limit= |
MusicBrainz-backed album search (used to resolve a missing track's album) |
POST /requests/albums |
{musicbrainz_id, album?, artist?, year?} → request one release group (playlist request --albums) |
POST /requests/tracks |
{recording_mbid, artist_name, track_title, album_title?, release_group_mbid?, duration_seconds?} → request one recording (default of playlist request) |
Authentication uses Authorization: Bearer <token>. An entry is considered
linked when it has a library_file_id, a track_source_id, or a non-empty
source_type; candidate available_sources alone do not count.
DELETE /library/albums/{id}is admin-only and requires both the album'srow_revisionandlisting_revision.delete_filesdefaults tofalseon the API, butneedlectldefaults to deleting files and requires--keep-filesto opt out.
DELETE /library/tracks/{id}requires the curator role (admin satisfies it) and the track'srow_revision.delete_filedefaults totrueon the API (the file moves to the recycle bin);needlectlexposes--keep-filesto senddelete_file=false. Since v3 has no single-track read endpoint,needlectlscans the library listing when it was not given the revision.
GET /playlists/{id}already includes the playlist's tracks; v3 has no separate track-list endpoint.
PATCH /playlists/{id}/tracks/{id}cannot attach a library file to an entry: it only storessource_type/available_sourcesand resolves the file from the album metadata already on the entry. Linking an existing entry therefore means replacing it (add at the same position, then remove the old one).
cover_urlon a playlist entry is client-supplied and stored verbatim: neitherPOST /playlists/{id}/tracksnorresolve-sourcesderives artwork from the linked library file, andPATCH /playlists/{id}/tracks/{id}ignores it (only source fields are writable). The playlist cover list is built from those same per-track values (SELECT DISTINCT cover_url … LIMIT 4), so entries added without a cover contribute neither per-track art nor a playlist image./api/v3/covers/release-group/{id}takes the MusicBrainz release-group id (release_group_mbidof a library track), not the localalbum_id.Library management (used by
album renameandtrack rename) must be active on the instance. Its edits are staged, journalled and published through file organization: a preview is created, then applied with itspreview_tokenand theoperation_row_revisionit reported. Fieldscopematters —album,album_artistand the*_sortfields are album-scoped, whiletitleandartistare track-scoped. These endpoints rewrite audio file tags.
POST /playlists/{id}/resolve-sourcesonly resolves entries that have both analbum_id(MusicBrainz release-group id) and atrack_number; entries without them keep their stored sources.
POST /import/uploadsaccepts only the multipartfilesfield: there is no way to attach a MusicBrainz reference at upload time. DroppedNeedle v3 removed the per-item match endpoint as well, so entries that end inneeds_reviewcan only be resolved in the server's web UI.
POST /held/{id}/matchtakes a release group, not a release;needlectlresolves a release URL or MBID to its group on musicbrainz.org before calling it. The endpoint imports every file of the entry and reports how many were imported, were already owned, stayed held or were discarded.
POST /requests/albumstakes a release-group MBID and answers 202. Curators get the download dispatched at once; other users getawaiting_approval. Duplicate asks attach to the live row.GET /search/albumsis the MusicBrainz-backed lookupplaylist requestuses to turn a playlist's album name into that id;in_libraryandrequestedon a hit tell whether a request is still needed.
POST /requests/trackstakes a recording MBID and fetches that one recording. The server's/search/tracksonly returns library rows, soplaylist requestresolves the recording from the album's MusicBrainz tracklist (release-group/{rg}?inc=releases, thenrelease/{id}?inc=recordings) and matches the playlist title exactly.
mise tasks # list every task
mise run build # compile ./bin/needlectl
mise run run # build and run (e.g. mise run run -- import file.csv)
mise run test # unit tests
mise run test:race # unit tests with the race detector
mise run cover # tests + coverage.out/coverage.html
mise run lint # go vet + gofmt check
mise run fmt # gofmt -w .
mise run tidy # go mod tidy
mise run install # go install .
mise run clean # remove build/coverage artifacts
mise run ci # lint + test:race + build.github/
workflows/release.yml tag-driven release: validate, test, build, publish
main.go entry point (calls cmd.Execute)
CHANGELOG.md complete technical history (Keep a Changelog)
cmd/
root.go root command, global flags, config loading
login.go interactive login
import.go import command group (upload + list)
import_playlist.go CSV playlist import
import_upload.go upload audio files
import_list.go list import batches and their entries
held.go held-entry list + MusicBrainz release match
album.go album delete + album rename commands
track.go track delete + track rename commands
tag_edit.go shared staged tag-edit flow (preview, confirm, apply)
playlist.go playlist command group and relink summary
playlist_repair_covers.go playlist cover repair command
playlist_request.go missing-track acquisition command (track or album)
internal/
config/ ~/.needlectl.conf load/save/validation
api/ typed DroppedNeedle REST client
playlist/ CSV parser
matcher/ normalization + library matching
link/ shared library-linking primitives
albums/ album query resolution (unique-match only)
tracks/ track query resolution (unique-match only)
mbref/ MusicBrainz reference, release-group and tracklist lookup
relink/ playlist relink plan + orchestration
covers/ playlist cover repair plan + orchestration
acquire/ missing-track album resolution + requests
importer/ pure import plan + orchestration
output/ coloured, structured terminal output
docs/
releases/ one Markdown file per release, used as release body
scripts/
release/build.sh cross-compile archives + SHA256SUMS
release/notes.sh compose the release body from docs + CHANGELOG
assets/
logo.png project logo, shown at the top of this README
The decision logic is pure and is the main unit-test target:
internal/importer/plan.go (what an import changes),
internal/relink/plan.go (which playlist entries can be linked),
internal/covers/plan.go (which cover URLs need repair) and
internal/acquire/plan.go (which missing albums and recordings resolve). The API
client is tested with httptest and each runner with an in-memory fake API.
| Symptom | Cause / fix |
|---|---|
config file not found: … |
Run needlectl login to create ~/.needlectl.conf. |
config file is incomplete: missing password |
Re-run needlectl login, or set NEEDLECTL_PASSWORD. |
… login failed: Invalid username or password |
Check the credentials stored in the config. |
| Login rejected with an unsupported-scheme or embedded-credentials error | Use http(s)://host[:port] and put credentials in the config, not the URL. |
| Certificate error against a self-signed instance | Pass --insecure (only if you trust the network path). |
Most tracks show as unlinked |
The tracks are not in the DroppedNeedle library yet. Scan the library, then re-run the import — it will relink them. |
library listing was truncated / repeated page cursor |
The server returned inconsistent pagination; the command refuses to run against a partial library. Re-run once the instance is healthy. |
refusing to guess: narrow the search with --artist or pass --id |
More than one album matched. Re-run with --artist, or copy the id from the listed candidates and use --id. |
refusing to guess: narrow the search with --artist/--album, or pass --id |
More than one track matched across albums. Re-run with --artist/--album, or copy the id from the listed candidates and use --id. |
refusing to guess: these matches share the album … |
Same-named tracks on one album, where --artist/--album cannot help. Re-run with --track (add --disc for multi-disc albums), or copy the id and use --id. |
--id cannot be combined with --artist, --album, --track or --disc |
--id skips the lookup, so the narrowing flags would be silently ignored. Pass one or the other. |
the staged preview is stale: … |
The album or the management settings changed between reading the tag editor and applying. Re-run album rename. |
the staged preview expired — run the command again |
Previews have a lifetime. Re-run album rename to stage a fresh one. |
the staged preview is not ready to apply (…) |
The server is still validating, or found no eligible files. Nothing was applied; check the instance's library management status. |
album … / track … cannot be renamed: its MusicBrainz identity has not been accepted (…) |
DroppedNeedle only allows metadata edits on albums whose identity is accepted, and a track's edits depend on its album. The message names the album state, the identification status and the review. Resolve that review first (accept the candidate, retry identification, keep-tagged, or reidentify the album), or tag the files with MusicBrainz ids and rescan. Nothing was staged. |
applying this writes the new name into the tags … then aborted |
You answered no to the confirmation, so the staged preview was discarded and nothing changed. |
unknown mode "…" (use save-override or write-once) |
Fix the --mode value. |
refusing to delete/import without confirmation; re-run with --yes |
The command ran without a terminal. Pass --yes to confirm non-interactively. |
held match reports no held entry … |
The entry is not among your held entries. Run needlectl held list and use the id it shows. |
playlist request reports unmatched tracks |
The album name/artist or the track title does not match MusicBrainz exactly. Fix the tags, request the album in the web UI, or pass --albums to request the whole release group. |
MusicBrainz answered 503 or repeated 429 |
The client retries with backoff. If it keeps failing, wait a minute and re-run; MusicBrainz allows about one request per second. |
too many albums match … |
The album query was too broad to page through. Refine the query or use --id. |
playlist "…" not found |
Check the name (needlectl playlist relink matches case-insensitively), or pass the id with --id. |
refusing to guess: pass the playlist id with --id |
Several playlists share that name. Copy the id from the listed candidates and use --id. |
playlist relink reports entries as unmatched |
Those tracks are not in the DroppedNeedle library yet. Scan the library, then re-run playlist relink. |
| A duplicate entry appears after an interrupted run | The refresh/relink inserts before removing; re-run the command to reconcile. |
Playlist exports contain personal listening data. *.csv files are gitignored
except for the synthetic fixture in internal/playlist/testdata/. Keep your
exports and ~/.needlectl.conf private.
- Playlists are matched by name.
importuses the first case-insensitive match;playlist relinkprefers correctness and refuses an ambiguous name, listing the candidates so you can pass--id. album deleterequires an admin account. By default it moves the album's files to the recycle bin;--keep-filesremoves only the catalog entry. It refuses to act when an album name is ambiguous, so it never deletes the wrong album.track deleterequires the curator role. By default it moves the track's file to the recycle bin;--keep-fileskeeps it on disk, though a library rescan may add it back as a new row. It refuses to act when a track name is ambiguous, and lists the candidates with their album, disc/track number, format and duration so a same-named track on the same album can be selected with--track/--discinstead of guessed at.playlist relinkonly touches entries that have no source at all. Entries that play through another source (Navidrome, Plex, Jellyfin) already have a link, so they are never re-pointed at the local library.album renamechanges the album field, which is album-scoped, so the whole album is renamed.track renamechanges only the track'stitle. Both require library management to be active and write into the audio file tags through the server's file organization, so they are staged, confirmed and applied rather than applied immediately. Other track-scoped fields (artist,genre, …) are not exposed as flags yet, and the server's identity gate applies to both.- Duration is stored but not used as a matching guard, so live/remix versions with very similar titles could be linked to the wrong file.
import uploadonly reports entries that are stillneeds_review; DroppedNeedle v3 dropped the API to resolve them, so it points at the web UI instead. Entries the server imported on its own are deliberately left alone: the API offers no documented way to re-match an entry that was already imported, and re-matching one has not been verified, so a wrong automatic match still has to be corrected in the web UI or by deleting and re-uploading.- The password is stored in plain text in a
0600file; an OS keyring backend would remove that class of risk. - The commands implemented so far are
login,playlist import,playlist relink,playlist repair-covers,playlist request,import upload,import list,held list,held match,album delete,album rename,track deleteandtrack rename.
Released under the MIT License. © 2026 mimnix.
