CLI Reference¶
This page is generated from the musicseed-cli Typer app
(musicseed_cli.app:app), using the same docstrings that power
musicseed-cli --help.
musicseed¶
Music recommendation CLI for Plex - create playlists based on seed tracks.
Usage¶
musicseed [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-v, --version |
No | - | |
-c, --config |
Path to config file | No | - |
--log-level |
File logging level: DEBUG, INFO, WARNING, ERROR | No | - |
--log-console |
Also print logs to stderr | No | False |
--log-console-level |
Console logging level | No | - |
--verbose |
Shortcut for --log-level DEBUG | No | False |
--install-completion |
Install completion for the current shell. | No | - |
--show-completion |
Show completion for the current shell, to copy it or customize the installation. | No | - |
Commands¶
| Name | Description |
|---|---|
init-db |
Initialize the database schema (creates... |
optimize-db |
Create database indexes for import,... |
status |
Show library statistics and enrichment... |
import |
Import metadata from the Plex database. |
sonic-probe |
Probe Plex sonic analysis coverage for a... |
sonic-refresh |
Refresh Plex sonic analysis for recently... |
enrich |
Enrich tracks with external metadata. |
recommend |
Preview recommendations from seed tracks... |
playlist |
Generate recommendations, prompt for... |
playlists |
List existing Plex audio playlists. |
populate |
Recommend complementary tracks for an... |
Subcommands¶
init-db¶
Initialize the database schema (creates tables).
Creates the SQLite database file and every table. Idempotent — safe to run again on an existing database.
Usage¶
musicseed init-db [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
optimize-db¶
Create database indexes for import, enrichment, and recommendation performance.
Usage¶
musicseed optimize-db [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
status¶
Show library statistics and enrichment status.
Usage¶
musicseed status [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
import¶
Import metadata from the Plex database.
Reads artists, albums, tracks, and play history from Plex's own SQLite database into MusicSeed. Incremental by default — pass --full for a complete re-import.
Usage¶
musicseed import [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--plex-db |
Path to Plex SQLite database | No | - |
-l, --library |
Plex library name to import | No | - |
--full |
Full re-import (default: incremental) | No | False |
sonic-probe¶
Probe Plex sonic analysis coverage for a music library.
Without flags this is read-only: it reports how many tracks Plex has sonically analyzed (overall and recently added) and lists the albums still pending. --trigger / --trigger-butler ask Plex to analyze one album and watch whether sonic analysis follows; both ask for confirmation first.
Usage¶
musicseed sonic-probe [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-l, --library |
Plex library name (default: config) | No | - |
--days |
Recent additions window in days | No | 7 |
--trigger |
Trigger Plex analysis on one unanalyzed album and watch whether sonic analysis follows | No | False |
--trigger-butler |
Trigger the Plex 'MusicAnalysis' Butler task (processes ALL pending albums, CPU-heavy) and watch one album for sonic analysis | No | False |
--album-key |
Album ratingKey to analyze/watch with --trigger/--trigger-butler | No | - |
--refresh |
Refresh the album's metadata first (re-reads files, clears failed-analysis state) before triggering | No | False |
--refresh-wait |
Seconds to let Plex re-scan after --refresh before triggering | No | 60 |
--wait |
Seconds to watch for sonic analysis after --trigger | No | 120 |
sonic-refresh¶
Refresh Plex sonic analysis for recently added music.
Triggers Plex's MusicAnalysis task and watches until the tracks added in
the last --days days are analyzed. Run import-plex-sonic afterwards to
pull the new vectors into MusicSeed.
Usage¶
musicseed sonic-refresh [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-l, --library |
Plex library name (default: config) | No | - |
--days |
Refresh sonic analysis for music added in the last N days | No | 7 |
--wait |
Max seconds to watch the refresh | No | 900 |
enrich¶
Enrich tracks with external metadata.
Fetches popularity and related metadata from ListenBrainz (default, requires a ListenBrainz user token — get one free at https://listenbrainz.org/settings/) or Spotify (requires configured client credentials). Use --resume to skip tracks that were already attempted.
Usage¶
musicseed enrich [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-s, --source |
Enrichment source | No | listenbrainz |
-b, --batch-size |
Tracks per batch | No | 50 |
-n, --limit |
Max tracks to enrich | No | - |
--artist |
Only enrich matching artist names; supports * and ? | No | - |
--album |
Only enrich matching album titles; supports * and ? | No | - |
-r, --resume |
Resume: skip already attempted tracks | No | False |
--concurrency |
Concurrent async requests | No | 5 |
recommend¶
Preview recommendations from seed tracks without writing to Plex.
Scores your local library against one or more seed tracks (--seed "Artist - Title" or --seed-id) across six signals: sonic similarity, popularity proximity, style, genre, era, and novelty. Use --explain to show the per-signal score breakdown and candidate sources.
Usage¶
musicseed recommend [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-s, --seed |
Seed track (Artist - Title) | No | - |
--seed-id |
Seed track by database ID | No | - |
-n, --limit |
Number of recommendations to return | No | 50 |
--explain |
Show component scores and candidate sources | No | False |
--w-sonic |
Sonic similarity weight | No | 0.3 |
--w-popularity |
Popularity proximity weight | No | 0.15 |
--w-style |
Style alignment weight | No | 0.1 |
--w-genre |
Genre alignment weight | No | 0.15 |
--w-era |
Era proximity weight | No | 0.05 |
--w-novelty |
Novelty weight | No | 0.1 |
--year-min |
Minimum release year | No | - |
--year-max |
Maximum release year | No | - |
--artist-max |
Max tracks per artist | No | 3 |
--min-score |
Exclude recommendations below this score (0.0–1.0) | No | - |
playlist¶
Generate recommendations, prompt for approval, then create a Plex playlist.
Shows the resolved seeds and recommended tracks first; the Plex playlist is only created after you confirm. The playlist contains the seed tracks followed by the approved recommendations.
Usage¶
musicseed playlist [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--name |
Plex playlist name (must be unique in Plex) | Yes | - |
-s, --seed |
Seed track (Artist - Title) | No | - |
--seed-id |
Seed track by database ID | No | - |
-n, --limit |
Number of tracks in the playlist | No | 50 |
--explain |
Show component scores and candidate sources | No | False |
--w-sonic |
Sonic similarity weight | No | 0.3 |
--w-popularity |
Popularity proximity weight | No | 0.15 |
--w-style |
Style alignment weight | No | 0.1 |
--w-genre |
Genre alignment weight | No | 0.15 |
--w-era |
Era proximity weight | No | 0.05 |
--w-novelty |
Novelty weight | No | 0.1 |
--year-min |
Minimum release year | No | - |
--year-max |
Maximum release year | No | - |
--artist-max |
Max tracks per artist | No | 3 |
--min-score |
Exclude recommendations below this score (0.0–1.0) | No | - |
playlists¶
List existing Plex audio playlists.
Usage¶
musicseed playlists [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
populate¶
Recommend complementary tracks for an existing Plex playlist, then add them.
Previews the recommendations first; tracks are only added after you confirm (--dry-run skips the write entirely). --method average scores against the playlist's mean profile; --method frequency gathers candidates from each playlist track individually and ranks by the average per-seed score.
Usage¶
musicseed populate [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--playlist |
Existing Plex playlist name to populate | Yes | - |
--method |
Recommendation strategy: 'average' (mean of playlist) or 'frequency' (vote count across per-track seeds) | No | average |
-n, --limit |
Number of tracks to add | No | 10 |
--per-seed-limit |
Candidates gathered per track (frequency method only) | No | 30 |
--explain |
Show component scores and vote sources | No | False |
--dry-run |
Preview recommendations only, skip the Plex write and confirmation | No | False |
--w-sonic |
Sonic similarity weight | No | 0.3 |
--w-popularity |
Popularity proximity weight | No | 0.15 |
--w-style |
Style alignment weight | No | 0.1 |
--w-genre |
Genre alignment weight | No | 0.15 |
--w-era |
Era proximity weight | No | 0.05 |
--w-novelty |
Novelty weight | No | 0.1 |
--year-min |
Minimum release year | No | - |
--year-max |
Maximum release year | No | - |
--artist-max |
Max tracks per artist | No | 3 |
--min-score |
Exclude recommendations below this score (0.0–1.0) | No | - |