discogs-sync

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 collecti

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 (exact versions pinned in requirements.txt, including transitive dependencies):

• python3-discogs-client==2.8 — Discogs API client
• click==8.3.1 — CLI framework
• rich==14.3.3 — Terminal output formatting

Installation (one-time, done by the user — not by the agent): create a venv at ~/.discogs-sync/venv and install the pinned requirements. discogs-sync.py picks up this venv automatically; it lives outside the skill directory so skill updates don't remove it.

bash

python3 -m venv ~/.discogs-sync/venv
~/.discogs-sync/venv/bin/pip install -r /home/claw/.openclaw/workspace/skills/discogs_sync/requirements.txt

discogs-sync.py never installs packages or launches other processes. If a dependency is missing it prints the commands above and exits with code 2.

Security & Permissions

• Network: HTTPS requests to api.discogs.com only.
• Filesystem: reads the input CSV/JSON file you pass; writes only under ~/.discogs-sync/ (config and cache files).
• Processes: none. No subprocess, shell, exec, or eval; no packages are installed at runtime.
• Credentials: one Discogs personal access token, read from DISCOGS_USER_TOKEN or from ~/.discogs-sync/config.json (created owner-only). The token is never printed or logged. Revoke it at https://www.discogs.com/settings/developers if compromised.

Agent rules for destructive operations: every removal (wantlist remove, collection remove, sync --remove-extras) is refused unless --yes is passed, and the refusal makes no changes.

1. Run the command without --yes first (for sync, add --dry-run). It resolves the target and exits with code 2, reporting exactly what would be removed: artist, title, release ID, and for collections the instance ID and number of copies owned. With --output-format json this preview is printed as {"confirmation_required": true, ...}.
2. Show that preview to the user and get explicit approval.
3. Only then re-run the same command with --yes.

• Never run auth on the user's behalf; it prompts for a secret and must be run by the user in a terminal.

Quick Start

bash

# Authenticate (one-time setup, run by the user)
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: preview (no change, exit 2), then confirm after user approval
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection remove --artist "Nirvana" --album "Nevermind"
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection remove --artist "Nirvana" --album "Nevermind" --yes

Authentication

The tool uses a Discogs personal access token. Generate one at https://www.discogs.com/settings/developers, then either:

• Environment variable (preferred): set DISCOGS_USER_TOKEN (e.g., via skills.entries.discogs-sync.apiKey in openclaw.json). It takes precedence over any stored token.
• One-time auth command: prompts for the token (input hidden), validates it against Discogs, and stores it in ~/.discogs-sync/config.json with owner-only permissions.

bash

python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py auth

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 (without --yes this only previews the target)
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist remove --artist "Radiohead" --album "OK Computer" [--yes]

# Remove by release ID
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist remove --release-id 7890 [--yes]

# 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 (removes one copy; without --yes this only previews the target)
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection remove --artist "Miles Davis" --album "Kind of Blue" [--yes]

# Remove by release ID
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection remove --release-id 7890 [--yes]

# 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 [--threshold 0.7] [--output-format json]

# Remove items not in the file: preview first, then confirm with --yes after user approval
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist sync albums.csv --remove-extras --dry-run
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py wantlist sync albums.csv --remove-extras --yes

# 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 | --remove-extras --yes]

# 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 (requires --dry-run or --yes)
--yes	remove, sync	Confirm a removal (remove, or sync --remove-extras). Without it, the command previews what would be removed, exits 2, and makes no changes

Output Format

Text (Default)

wantlist list / collection list:

text

                           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:

text

                               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:

text

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 uses a Discogs personal access token from DISCOGS_USER_TOKEN or the one-time auth command.
• 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.
• --remove-extras removes wantlist/collection items that are not in the input file. It refuses to run without --yes (or --dry-run), and aborts before making any change if any input record failed to resolve, so a bad match can't delete the real item.
• remove commands require --yes. Without it they only report the exact release (and collection instance) that would be removed; with it they print that release before deleting it.
• 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_<type>_<hash>.json (plus …_details.json variants). Delete any of these files to manually clear a stale cache entry.
• ~/.discogs-sync/config.json holds your token when you use auth; the tool creates it owner-only. Revoke tokens at https://www.discogs.com/settings/developers if compromised.