Quick Start Guide

This guide will help you get started with Record Shelf in just a few minutes.

Step 1: Get Your Discogs API Token

Before using Record Shelf, you need a Discogs API token:

  1. Go to Discogs Developer Settings

  2. Create a new application or use an existing one

  3. Generate a personal access token

  4. Copy your token for use with Record Shelf

Warning

Keep your API token secure! Don’t share it publicly or commit it to version control.

Step 2: Set Up Your Token

You can provide your token in two ways:

Option 1: Environment Variable (Recommended):

export DISCOGS_TOKEN="your_token_here"

Option 2: Command Line Flag:

record-shelf --token "your_token_here" [command]

Step 3: Your First Report

Generate a complete collection report:

record-shelf generate --username YOUR_DISCOGS_USERNAME

This will create a file called collection_report.xlsx with your entire collection.

Step 4: Explore Your Collection

List available shelves in your collection:

record-shelf list-shelves --username YOUR_DISCOGS_USERNAME

Example output:

Available shelves:
  - All
  - Vinyl
  - CD
  - Digital
  - Wishlist

Step 5: Customize Your Reports

Filter by shelf:

record-shelf generate --username YOUR_DISCOGS_USERNAME --shelf "Vinyl"

Change output format:

record-shelf generate --username YOUR_DISCOGS_USERNAME --format csv

Specify output filename:

record-shelf generate --username YOUR_DISCOGS_USERNAME --output my_collection.xlsx

Enable debug logging:

record-shelf --debug generate --username YOUR_DISCOGS_USERNAME

Common Examples

Here are some common use cases:

Vinyl collection to Excel:

record-shelf generate --username myuser --shelf "Vinyl" --output vinyl_collection.xlsx

Complete collection to CSV:

record-shelf generate --username myuser --format csv --output complete_collection.csv

HTML report for web viewing:

record-shelf generate --username myuser --format html --output collection.html

Debug a specific shelf:

record-shelf --debug generate --username myuser --shelf "CD" --output cd_debug.xlsx

Understanding the Output

Record Shelf generates reports with the following columns:

  • Shelf: Collection folder/shelf name

  • Artist: Artist name(s)

  • Title: Release title

  • Label: Record label(s)

  • Catalog Number: Label catalog number(s)

  • Format: Format details (e.g., “Vinyl, LP, Album”)

  • Year: Release year

  • Genre: Music genre(s)

  • Style: Music style(s)

  • Country: Country of release

  • Discogs ID: Unique Discogs release ID

  • Master ID: Master release ID (if applicable)

  • Rating: Your rating (if set)

  • Notes: Your personal notes (if any)

Excel Format Features:

  • Main “Collection” sheet with all items

  • Separate sheet for each shelf

  • Sortable columns and formatting

Troubleshooting

Authentication Error

  • Verify your Discogs token is correct

  • Check if token is set via environment variable or –token option

Empty Collection

  • Verify the username is correct

  • Check if the collection is public

  • Ensure the user has items in their collection

Rate Limiting

  • Record Shelf includes built-in rate limiting

  • If you see rate limit errors, try again in a few minutes

Missing Data

  • Some Discogs entries may have incomplete information

  • This is normal and will show as empty fields in the report

Next Steps

Now that you’ve generated your first report, explore more features: