discogs_sync

---
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. Identify the exact pressing of a record from the
  matrix/runout etchings in its dead wax, and swap a collection entry to the correct pressing.
  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, find what a record is selling
  for, or figure out which pressing they own from its runout. Also supports bulk operations
  via CSV/JSON file input. Requires a Discogs personal access token, supplied via the
  DISCOGS_USER_TOKEN environment variable or a one-time `auth` command. Only contacts
  api.discogs.com.
metadata: {"openclaw":{"emoji":"🎵","requires":{"bins":["python3"]},"primaryEnv":"DISCOGS_USER_TOKEN"}}
---

# 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`, `collection replace`, `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.

### Collection — Replace with the Correct Pressing

```bash
# Preview (no change, exit 2), then confirm after user approval
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection replace --release-id 29576638 --old-release-id 9697557
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection replace --release-id 29576638 --old-release-id 9697557 --yes

# When several copies of the old release are owned, pick one by instance
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection replace --release-id 29576638 --instance-id 2124303711 [--yes]
```

Discogs can't change which release a collection entry points to, so `replace` adds the new release to the old entry's folder, copies its rating and custom fields (Media Condition, Sleeve Condition, Notes), then removes the old entry. If copying fails, the old entry is kept and the error says so. Always use `replace` rather than `add` + `remove` when correcting a pressing — a plain `remove` discards the condition grades.

### Collection — Edit Rating, Condition, and Notes

```bash
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection edit --instance-id 2193329280 --media-condition NM --sleeve-condition "VG+" [--rating 4] [--output-format json]
python3 /home/claw/.openclaw/workspace/skills/discogs_sync/discogs-sync.py collection edit --release-id 8858783 --notes "Matrix engraved over 1-23771"
```

Sets a collection entry's rating (1–5, `0` clears) and custom fields, looked up by name: Media Condition, Sleeve Condition (dropdowns; accept the full option, its name, or its abbreviation such as `NM`, `M-`, `VG+`, `Generic`), and Notes (free text; replaces existing notes, `""` clears). Use `--instance-id` when several copies are owned. Only differing values a

... (truncated)