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

Search — find entities by name

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

Inspect — get full details using refs from search output
```
agent-discogs get release @r367113
```

Drill down — tracklist, pricing

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

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

Goal	Commands
Find a specific pressing	`search release "<title>" --year --country` → `get release @r...`
Compare pressings	`search master "<title>"` → `get versions @m...`
Explore discography	`search artist "<name>"` → `get releases @a...`
Check price	`search release "<title>"` → `price @r...`
Identify by catalog number	`search release --catno "INT-92346"` → `get release @r...`
Find by barcode	`search release --barcode "606949235024"`
Get original pressing	`search master "<title>"` → `get versions @m...` → `get release @r...`
Narrow release search	`search release "<title>" --artist "<name>"`
Get release notes	`get release @r... --verbose`
Get artist/label IDs from a release	`get release @r... --verbose` — inline `[@a...]` and `[@l...]` refs
VA compilation tracks	`get release @r...` — per-track artists shown automatically
Machine-readable output	Add `--json` to any command for raw JSON

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

Document	Content
references/commands.md	Full command reference with all flags
references/search-patterns.md	Effective search strategies
references/pressings-guide.md	Master/release/version mental model
references/discogs-domain.md	Discogs data model: formats, genres, country, artists, labels, identifiers