coverart-cli

Fill the missing covers in your music library — embed and sidecar in one pass.

What it does

Most cover-art tools only embed or only sidecar. That breaks across players — Subsonic apps (Amperfy, Symfonium) read tags, Plex / Jellyfin prefer cover.jpg, Apple Music wants embedded. coverart-cli does both in one pass and ships an HTML coverage report so you can see what's still missing.

Install

pipx install coverart-cli

Requires Python 3.11 or newer. Upgrade an existing installation with pipx upgrade coverart-cli.

Quick start

# 1. Preview the exact library first; this performs no writes
coverart ~/Music --dry-run -v

# 2. Fetch + embed + sidecar (free providers, no key needed)
coverart ~/Music

# Optional: add Last.fm as the first provider
LASTFM_API_KEY=your-key coverart ~/Music

# Just generate the coverage report
coverart ~/Music --report-only --report-html report.html

# Only write cover.jpg files; leave audio tags unchanged
coverart ~/Music --no-embed

Run coverart --help for the full flag list.

By default, an album is complete only when it has a usable sidecar and every supported audio file has embedded artwork. If a local sidecar already exists, it is reused to fill missing embeds without a network request. Symbolic links to album directories, audio files, or sidecars are ignored, so writes stay inside the selected library.

Before the first non-dry run, keep a backup of irreplaceable music files. Tag writes are handled by Mutagen, but any bulk metadata operation deserves a recovery path.

Config file

Save your defaults so you don't have to repeat flags:

# ~/.config/coverart-cli/config.toml
lastfm_key      = "your-key"
min_bytes       = 30000
replace_smaller = true
no_musicbrainz  = false

Lookup order (later wins): built-in defaults → ~/.config/coverart-cli/config.toml → ./coverart.toml → --config PATH → CLI flags. LASTFM_API_KEY overrides the configured key unless --lastfm-key is supplied. Run coverart ~/Music afterwards with no repeated flags.

Sources

Tried in order until a cover is found:

1. Last.fm — album.getinfo (needs a free API key)
2. iTunes — Apple Music's public search, no key
3. Deezer — public API, no key
4. MusicBrainz + Cover Art Archive — fallback for niche releases

Album and artist names are sent to the enabled providers over HTTPS. Download URLs and redirects are restricted to the providers' API and image hosts; arbitrary hosts and non-HTTPS URLs are rejected.

Supported formats

MP3 (ID3 APIC), M4A/M4B/MP4 (covr atom), FLAC (Picture block), Ogg Vorbis / Opus (metadata_block_picture).

Common workflows

Use --workers 1 for deterministic serial processing or when a provider is rate-limiting heavily. MusicBrainz requests are always rate-limited internally.

Programmatic use

from pathlib import Path
from coverart_cli.core import RunOptions, run
from coverart_cli.providers import ITunesProvider, DeezerProvider

stats = run(RunOptions(
    root=Path("~/Music").expanduser(),
    providers=[ITunesProvider(), DeezerProvider()],
))
print(stats.fetched_from, stats.not_found)

Alternatives

Development

git clone https://github.com/buettgen-app/coverart-cli && cd coverart-cli
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check . && pyrefly check && pytest

Releases

Releases are prepared by release-please and published from an immutable Git tag via PyPI Trusted Publishing. Commits to main follow Conventional Commits:

The Prepare release workflow uses the repository-scoped GITHUB_TOKEN to open and update one rolling Release PR. Merging that PR creates the version tag and publishes the GitHub Release. Because GitHub intentionally suppresses the release event created by its workflow token, the same trusted run sends an authenticated repository dispatch to the isolated Publish release workflow. That workflow verifies the source workflow run, release tag, exact commit, package metadata, and changelog. It builds one wheel and source distribution, attaches those exact files to the GitHub Release, and publishes them to PyPI with OIDC attestations.

No release App, private key, or personal access token is required. In Settings → Actions → General → Workflow permissions, enable Allow GitHub Actions to create and approve pull requests. GitHub may hold checks on a Release Please PR until a maintainer selects Approve workflows to run; this approval remains part of the manual release gate.

The PyPI Trusted Publisher must be configured for GitHub owner buettgen-app, repository coverart-cli, workflow release.yml, and environment pypi. That filename is the stable publish identity even though Release Please itself runs in prepare-release.yml. Do not create release tags or upload distributions by hand. A failed publish can be rerun from the same GitHub Actions run without introducing a second release path. Historical releases can be recovered by manually running the same workflow from main; it accepts only an existing published release tag and applies every normal validation and test gate. Pull requests and Release PRs require an explicit merge after branch protection passes. Verified low-risk Dependabot patch updates, development-only minor updates, and GitHub Actions minor updates use GitHub's native auto-merge; major and production minor updates remain manual. GitHub Actions changes are gated by the repository's Zizmor security lint; third-party AI review remains advisory so availability limits cannot block security updates.

License

MIT