docs(cli): document the artwork command group - #422
Open
deluan wants to merge 3 commits into
Open
Conversation
Adds reference docs for navidrome artwork (status, explain, refresh, reprocess), which lands in the server as PR navidrome/navidrome#5957. Covers the per-command kind support, since it is not uniform: explain takes all six kinds, refresh excludes disc (it keeps no state to clear), and reprocess covers only the four kinds the backfill revisits. Also documents the chain outcome vocabulary — notably unreadable vs miss, which is the distinction stored state cannot express — and the offline-by-default behaviour of explain. Links the Artwork resolution page to the new section from a Troubleshooting heading.
Preview Deployment
Built from 0a0d321 |
This was referenced Aug 15, 2026
The artwork commands load the plugins named in Agents so they can report the same agent list a running server resolves through. Loading a plugin creates the services its manifest declares, and --live additionally runs each plugin's init, which may open external connections. Worth stating on a page whose main promise is that explain makes no external requests by default.
explain/refresh now accept a bare id or a full artwork id (al-<id>), not just a <kind> <id> pair; refresh can mix kinds and skips unresolvable ids.
deluan
marked this pull request as ready for review
August 19, 2026 20:30
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documents the
navidrome artworkcommand group —status,explain,refreshandreprocess— which lands in the server as navidrome/navidrome#5957. These commands exist so "my artwork is wrong/missing" reports can be answered without direct database access, so the docs are written around that workflow rather than as a flag dump.Three things needed more than a flag list:
explaintakes all six kinds;refreshexcludesdcbecause disc artwork keeps no stored state to clear;reprocesscovers only the four kinds the backfill revisits. There's a small table for this, plus the reason in prose.unreadablevsmiss. That's the distinction stored state cannot express — a damaged file worth fixing versus nothing being there — and it's the main reasonexplainexists.explainis offline by default. External agents are reported aswould-tryrather than called, and--liveopts in. Worth calling out, since the situation you're most likely debugging is a provider rate-limiting you.The
statussection leads with the backfill fingerprint, because that's the one line that explains a surprise burst of external requests: changingAgents(or any of five other settings) silently re-resolves every artist, album, playlist and radio on the next startup.Also adds a short Troubleshooting section to Artwork resolution pointing at the new commands, so the page describing the priority chains links to the tool that shows you a chain being walked.
All command syntax, flags and help text were taken from
--helpon a build of the branch, not from memory. The example outputs are real command output with library paths replaced.Type of change
Checklist
npm start) when relevantnpm run build)Verified
npm run build(100 pages, no errors) and checked the rendered HTML: both tables render as tables, the alerts render, the#artworkanchor exists, and the cross-link from the artwork page resolves to it.