agent-discogs

CLI for searching and exploring the Discogs music database. Returns compact text output with a ref system for chaining commands.

Setup

Requires DISCOGS_TOKEN for full access (60 req/min, search, price data):

export DISCOGS_TOKEN=<your-token>  # discogs.com/settings/developers

Without a token: 25 req/min, no search, no price suggestions.

Check status: agent-discogs status

Core Workflow

1. Search — find entities by name

   agent-discogs search release "The Downward Spiral" --year 1994
   

2. Inspect — get full details using refs from search output

   agent-discogs get release @r367113
   

3. Drill down — tracklist, pricing

   agent-discogs tracks @r367113
   agent-discogs price @r367113
   

4. Explore — discography, versions

   agent-discogs get versions @m4917 --country US
   

Output Format

• search — numbered list of matches with refs, title, year, format. Replaces all stored refs.
• get release — title, artists, label, format, tracklist summary, notes. Adds ref.
• get release --verbose — full details including inline [@a...] and [@l...] refs for chaining.
• tracks — numbered tracklist with durations and per-track artists (for VA releases).
• price — price suggestions by condition (Mint, Near Mint, VG+, etc.) and marketplace stats.
• get versions — table of pressings with country, year, format, label, and refs.
• get releases — artist discography with type, year, and refs.

Common Patterns

Machine-Readable Output

All commands support --json for raw JSON output, useful for piping into other tools or extracting structured data:

agent-discogs search release "Blue Monday" --artist "New Order" --json
agent-discogs get release @r367113 --json

Anti-Patterns

• Don't search without a type filter when you know the entity type.
• Don't fetch full release details just to check price. Use price @r... directly.
• Don't paginate through all results. Narrow with filters first.
• Don't guess IDs. Always search first to find the right entity.
• Don't use get versions on a release ID. Use a master ref (smart resolution costs an extra API call).

Error Recovery

• 0 results — broaden filters (drop --year, --country), try a different type (master instead of release), or simplify the query.
• Auth required — price suggestions and search require DISCOGS_TOKEN. Run agent-discogs status to check.
• Invalid ref — refs are session-scoped and reset on each search. Re-search to get fresh refs.
• Rate limited — wait briefly and retry. Authenticated requests get 60/min; unauthenticated get 25/min.

Refs

Refs encode entity type and Discogs ID: @a3857 (artist), @r367113 (release), @m4917 (master), @l2919 (label). Raw numeric IDs also work.

Ref chaining: get release @r... --verbose embeds inline [@a...] and [@l...] refs in the output. Use these to chain into artist discographies or label catalogs without an extra search.

Key Concepts

Master = canonical album. Release = specific pressing. Version = a release belonging to a master. Search masters to find all pressings; search releases to find a specific one. See references/pressings-guide.md for details.

Formats, genres, identifiers, and other Discogs-specific data conventions are documented in references/discogs-domain.md.

Token Efficiency

Prefer the most specific command: tracks @r... over get release @r... when you only need the tracklist, and price @r... over get release @r... when you only need pricing. This reduces output tokens and avoids unnecessary data.

Reference Docs