--- name: leoyeai/discogs-sync source: https://app.decimal.ai/s/leoyeai-discogs-sync@1/SKILL.md source_sha256: e05ca20c27a4 --- # 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. ## Runtime & Dependencies **Runtime:** Python 3.10+ **Python packages** (installed automatically on first run): - `python3-discogs-client>=2.8` — Discogs API client - `click>=8.1` — CLI framework - `rich>=13.0` — Terminal output formatting **Installation:** No manual `pip install` needed. On first run, `discogs-sync.py` creates a local `.deps/` virtual environment inside the skill directory and installs dependencies from `requirements.txt`. Subsequent runs reuse the existing venv. This works on macOS (including Homebrew Python), Linux, and Windows without requiring system-level package installation. To force a clean reinstall of dependencies, delete the `.deps/` directory and run any command again. ## Quick Start ```bash # Authenticate (one-time setup — also installs dependencies on first run) python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py auth # Add an album to your wantlist by name python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist add --artist "Radiohead" --album "OK Computer" # Add to your collection by release ID python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection add --release-id 7890 # Check marketplace prices for a vinyl pressing python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py marketplace search --artist "Miles Davis" --album "Kind of Blue" --format Vinyl # List your wantlist python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist list # Remove from collection python3 /home/claw/.openclaw/workspace/skills/discogs_sync/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. ```bash python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py auth python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py auth --mode token ``` **OAuth 1.0a** — full OAuth flow with consumer key/secret, for apps that need delegated access. ```bash python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py auth --mode oauth ``` Credentials are stored in `~/.discogs-sync/config.json`. ```bash # Verify authentication python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py whoami python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py whoami --output-format json ``` ## Usage ### Wantlist — Add, Remove, List ```bash # Add by artist/album name python3 /home/claw/.openclaw/workspace/skills/discogs_sync/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) python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist add --master-id 3425 # Add by specific release ID python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist add --release-id 7890 # Remove by artist/album name python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist remove --artist "Radiohead" --album "OK Computer" # Remove by release ID python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist remove --release-id 7890 # List current wantlist python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist list [--search "QUERY"] [--format Vinyl] [--year 1997] [--no-cache] [--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 ```bash # Add by artist/album name python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection add --artist "Miles Davis" --album "Kind of Blue" [--format Vinyl] # Add by master ID or release ID python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection add --master-id 3425 [--folder-id 1] python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection add --release-id 7890 [--folder-id 1] # Add a second copy of something already owned python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection add --release-id 7890 --allow-duplicate # Remove by artist/album name python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection remove --artist "Miles Davis" --album "Kind of Blue" # Remove by release ID python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection remove --release-id 7890 # List collection (all folders) python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection list [--search "QUERY"] [--format CD] [--year 1959] [--folder-id 0] [--no-cache] [--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 ```bash # Search by artist/album name python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py marketplace search --artist "Radiohead" --album "OK Computer" [--format Vinyl] [--country US] [--output-format json] # Search by master ID python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py marketplace search --master-id 3425 [--format Vinyl] [--country US] # Search by specific release ID (skips master version scan) python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py marketplace search --release-id 7890 # Filter by price range and country python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py marketplace search --artist "Pink Floyd" --album "The Dark Side of the Moon" --format Vinyl --country US --min-price 10 --max-price 50 --currency USD # Show detailed progress and condition grade price suggestions python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py marketplace search --artist "Radiohead" --album "OK Computer" --verbose --details ``` Returns release versions sorted by lowest price, with number of copies for sale. Single-item results are cached for 1 hour by lookup parameters. With `--details`, a separate details cache entry is used; if only the base cache is warm the tool fetches just the condition-grade price suggestions rather than re-running the full search. Pass `--no-cache` to force a live fetch (result is still written to cache). ### Bulk Operations via File For batch operations, pass a CSV or JSON file instead of individual `--artist`/`--album` flags. ```bash # Sync wantlist from file (preview first with --dry-run) python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist sync albums.csv --dry-run python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist sync albums.csv [--remove-extras] [--threshold 0.7] [--output-format json] # Sync collection from file python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection sync albums.csv [--folder-id 1] [--remove-extras] [--dry-run] # Batch marketplace search from file python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py marketplace search albums.csv [--format Vinyl] [--country US] [--max-price 50] [--max-versions 25] [--output-format json] ``` **CSV format** (header row required, `artist` and `album` required): ```csv 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): ```json [ {"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, list, marketplace search | Filter by format: Vinyl, CD, Cassette (synonyms like LP, record are normalized) | | `--year` | list | Filter by release year (exact match) | | `--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 | | `--country` | marketplace search | Filter by country of pressing (exact match: US, UK, Germany, etc.) | | `--release-id` | marketplace search | Fetch stats for a specific release (bypasses master version scan) | | `--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) | | `--details` | marketplace search | Include suggested prices by condition grade | | `--no-cache` | list, marketplace search | Bypass local cache; fresh results are still written back to cache | | `--verbose` | sync, marketplace search | Show detailed progress and API call logging | | `--search` | list | Filter results by artist or title (case-insensitive substring match) | | `--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:** ```json { "items": [ { "release_id": 7890, "master_id": 3425, "title": "OK Computer", "artist": "Radiohead", "format": "Vinyl", "year": 1997 } ], "total": 1 } ``` **marketplace search:** ```json { "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:** ```json { "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 `python3 /home/claw/.openclaw/workspace/skills/discogs_sync/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. - Cache files are stored in `~/.discogs-sync/` alongside `config.json`: `wantlist_cache.json`, `collection_cache.json`, and `marketplace__.json` (plus `…_details.json` variants). Delete any of these files to manually clear a stale cache entry. - 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.