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.

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

# 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.

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

# 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

# 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

# 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

# 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.

# 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):

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, 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:

                           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 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.