name: discogs-sync description: > Add and remove albums from a Discogs wantlist or collection by artist and album name, master ID, or release ID. Search marketplace pricing for vinyl, CD, and other formats. List wantlist and collection contents. Use when the user asks to add or remove a record from their Discogs wantlist or collection, check what's on their wantlist, look up marketplace prices, or find what a record is selling for. Also supports bulk operations via CSV/JSON file input. metadata: {"openclaw":{"emoji":"🎵","requires":{"bins":["python3","pip3"]}}}

Discogs Sync — Wantlist, Collection & Marketplace CLI

Add and remove albums from your Discogs wantlist or collection, search marketplace pricing, and list what you have. Identify albums by artist/album name, Discogs master ID, or release ID. For bulk operations, pass a CSV or JSON file.

Prerequisites

Python 3.10+ and the following packages are required:

pip install -r requirements.txt

Or install directly:

pip install "python3-discogs-client>=2.8" "click>=8.1" "rich>=13.0"

Quick Start

# Authenticate (one-time setup)
python discogs-sync.py auth

# Add an album to your wantlist by name
python discogs-sync.py wantlist add --artist "Radiohead" --album "OK Computer"

# Add to your collection by release ID
python discogs-sync.py collection add --release-id 7890

# Check marketplace prices for a vinyl pressing
python discogs-sync.py marketplace search --artist "Miles Davis" --album "Kind of Blue" --format Vinyl

# List your wantlist
python discogs-sync.py wantlist list

# Remove from collection
python discogs-sync.py collection remove --artist "Nirvana" --album "Nevermind"

Authentication

Run once to authenticate. Two modes are available:

Personal access token (default) — simplest option. Generate a token at https://www.discogs.com/settings/developers.

python discogs-sync.py auth
python discogs-sync.py auth --mode token

OAuth 1.0a — full OAuth flow with consumer key/secret, for apps that need delegated access.

python discogs-sync.py auth --mode oauth

Credentials are stored in ~/.discogs-sync/config.json.

# Verify authentication
python discogs-sync.py whoami
python discogs-sync.py whoami --output-format json

Usage

Wantlist — Add, Remove, List

# Add by artist/album name
python discogs-sync.py wantlist add --artist "Radiohead" --album "OK Computer" [--format Vinyl]

# Add by Discogs master ID (resolves to main release, or filters by --format)
python discogs-sync.py wantlist add --master-id 3425

# Add by specific release ID
python discogs-sync.py wantlist add --release-id 7890

# Remove by artist/album name
python discogs-sync.py wantlist remove --artist "Radiohead" --album "OK Computer"

# Remove by release ID
python discogs-sync.py wantlist remove --release-id 7890

# List current wantlist
python discogs-sync.py wantlist list [--search "QUERY"] [--output-format json]

Duplicate check: skips if the release is already in the wantlist (by release_id, master_id, or fuzzy artist+title match).

Collection — Add, Remove, List

# Add by artist/album name
python discogs-sync.py collection add --artist "Miles Davis" --album "Kind of Blue" [--format Vinyl]

# Add by master ID or release ID
python discogs-sync.py collection add --master-id 3425 [--folder-id 1]
python discogs-sync.py collection add --release-id 7890 [--folder-id 1]

# Add a second copy of something already owned
python discogs-sync.py collection add --release-id 7890 --allow-duplicate

# Remove by artist/album name
python discogs-sync.py collection remove --artist "Miles Davis" --album "Kind of Blue"

# Remove by release ID
python discogs-sync.py collection remove --release-id 7890

# List collection (all folders)
python discogs-sync.py collection list [--search "QUERY"] [--folder-id 0] [--output-format json]

Duplicate check: by default, add skips if the release is already in the collection (by release_id, master_id, or fuzzy artist+title match). Use --allow-duplicate to add another copy.

Marketplace — Search Pricing

# Search by artist/album name
python discogs-sync.py marketplace search --artist "Radiohead" --album "OK Computer" [--format Vinyl] [--output-format json]

# Search by master ID
python discogs-sync.py marketplace search --master-id 3425 [--format Vinyl]

# Filter by price range
python discogs-sync.py marketplace search --artist "Pink Floyd" --album "The Dark Side of the Moon" --format Vinyl --min-price 10 --max-price 50 --currency USD

Returns release versions sorted by lowest price, with number of copies for sale.

Bulk Operations via File

For batch operations, pass a CSV or JSON file instead of individual --artist/--album flags.

# Sync wantlist from file (preview first with --dry-run)
python discogs-sync.py wantlist sync albums.csv --dry-run
python discogs-sync.py wantlist sync albums.csv [--remove-extras] [--threshold 0.7] [--output-format json]

# Sync collection from file
python discogs-sync.py collection sync albums.csv [--folder-id 1] [--remove-extras] [--dry-run]

# Batch marketplace search from file
python discogs-sync.py marketplace search albums.csv [--format Vinyl] [--max-price 50] [--max-versions 25] [--output-format json]

CSV format (header row required, artist and album required):

artist,album,format,year,notes
Radiohead,OK Computer,Vinyl,,Must have
Miles Davis,Kind of Blue,,1959,Original pressing
Nirvana,Nevermind,CD,1991,

JSON format (array of objects with the same fields):

[
    {"artist": "Radiohead", "album": "OK Computer", "format": "Vinyl"},
    {"artist": "Miles Davis", "album": "Kind of Blue", "year": 1959}
]

Format synonyms are normalized automatically: LP/record/12" → Vinyl, compact disc → CD, tape/mc → Cassette.

Options

| Option | Applies To | Description | |--------|-----------|-------------| | --output-format | All | table (default) or json for machine-readable output | | --threshold | add, remove, search, sync | Match score threshold 0.0–1.0 (default: 0.7) | | --format | add, marketplace search | Filter by format: Vinyl, CD, Cassette | | --folder-id | collection | Target folder (default: 1 for adds, 0 for reads) | | --allow-duplicate | collection add | Allow adding another copy of an album already in collection | | --min-price | marketplace | Minimum price filter | | --max-price | marketplace | Maximum price filter | | --currency | marketplace | Currency code (default: USD) | | --max-versions | marketplace | Max release versions to check per master (default: 25) | | --search | list | Filter results by artist or title (case-insensitive substring) | | --dry-run | sync | Preview changes without modifying Discogs | | --remove-extras | sync | Remove wantlist/collection items not in the input file |

Output Format

Text (Default)

wantlist list / collection list:

                           Wantlist
┌────────────┬───────────┬─────────────┬─────────────┬────────┬──────┐
│ Release ID │ Master ID │ Artist      │ Title       │ Format │ Year │
├────────────┼───────────┼─────────────┼─────────────┼────────┼──────┤
│ 7890       │ 3425      │ Radiohead   │ OK Computer │ Vinyl  │ 1997 │
│ 1234       │ 1000      │ Miles Davis │ Kind of Blue│ Vinyl  │ 1959 │
└────────────┴───────────┴─────────────┴─────────────┴────────┴──────┘

Total: 2

marketplace search:

                               Marketplace Results
┌───────────┬────────────┬───────────┬─────────────┬────────┬──────────┬──────────────┐
│ Master ID │ Release ID │ Artist    │ Title       │ Format │ For Sale │ Lowest Price │
├───────────┼────────────┼───────────┼─────────────┼────────┼──────────┼──────────────┤
│ 3425      │ 7890       │ Radiohead │ OK Computer │ Vinyl  │ 42       │ 25.99 USD    │
│ 3425      │ 15432      │ Radiohead │ OK Computer │ Vinyl  │ 18       │ 32.50 USD    │
└───────────┴────────────┴───────────┴─────────────┴────────┴──────────┴──────────────┘

add / remove result:

Sync Report
  Total input: 1
  Added:   1
  Removed: 0
  Skipped: 0
  Errors:  0

JSON (--output-format json)

wantlist list / collection list:

{
  "items": [
    {
      "release_id": 7890,
      "master_id": 3425,
      "title": "OK Computer",
      "artist": "Radiohead",
      "format": "Vinyl",
      "year": 1997
    }
  ],
  "total": 1
}

marketplace search:

{
  "results": [
    {
      "master_id": 3425,
      "release_id": 7890,
      "title": "OK Computer",
      "artist": "Radiohead",
      "format": "Vinyl",
      "country": "US",
      "year": 1997,
      "num_for_sale": 42,
      "lowest_price": 25.99,
      "currency": "USD"
    }
  ],
  "total": 1
}

add / remove / sync report:

{
  "summary": {
    "total_input": 1,
    "added": 1,
    "removed": 0,
    "skipped": 0,
    "errors": 0
  },
  "actions": [
    {
      "action": "add",
      "artist": "Radiohead",
      "title": "OK Computer",
      "release_id": 7890,
      "master_id": 3425,
      "reason": null,
      "error": null
    }
  ]
}

Output Fields

• release_id — Unique Discogs release identifier
• master_id — Discogs master release identifier (groups all versions of an album)
• title — Album title
• artist — Artist name
• format — Physical format (Vinyl, CD, Cassette, etc.)
• year — Release year
• country — Country of release
• num_for_sale — Number of copies currently for sale on the marketplace
• lowest_price — Lowest listed price for the release
• currency — Price currency code
• instance_id — Collection-specific instance identifier (for duplicate copies)
• folder_id — Collection folder identifier
• action — Sync action taken: add, remove, skip, or error

Release Matching

When using --artist and --album, the tool runs a multi-pass search to find the best Discogs match:

1. Structured search — artist, album, format, and year
2. Relaxed search — drops format and year constraints
3. Free text search — searches "artist album" as plain text

Each result is scored 0.0–1.0: 40% artist similarity + 40% title similarity + 10% year match + 10% format match. Results below --threshold (default 0.7) are rejected. Lower the threshold for fuzzy matches.

When using --master-id or --release-id, no search is needed — the ID is used directly.

Exit Codes

• 0 — Success (all items processed)
• 1 — Partial failure (some items failed)
• 2 — Complete failure (no items processed, or auth/config error)

Notes

• Authentication supports personal access tokens (default) and OAuth 1.0a. Run python discogs-sync.py auth once.
• The Discogs API is rate-limited to 60 requests/minute for authenticated users. The tool throttles automatically — no manual pacing needed.
• Batch operations are resilient: individual item failures are collected and reported without aborting the entire batch.
• Use --dry-run before any sync to preview what would change. This makes no API writes.
• The --remove-extras flag on sync commands will remove items from your wantlist/collection that are not in the input file. Use with caution.
• Collection allows multiple instances of the same release (e.g., two copies of the same LP). By default, collection add skips duplicates with a message. Use --allow-duplicate to add another copy.
• Credentials in ~/.discogs-sync/config.json contain your Discogs tokens. On Linux/macOS, restrict permissions: chmod 600 ~/.discogs-sync/config.json. Revoke tokens at https://www.discogs.com/settings/developers if compromised.