Goodreads Tool

A comprehensive command-line tool for processing Goodreads library exports and converting them into Obsidian notes, with powerful filtering and analysis capabilities.

Features

• 📚 Convert to Obsidian Notes: Transform your Goodreads library into beautifully formatted Obsidian markdown notes
• 📊 Library Analysis: Get detailed statistics about your reading habits, ratings, and progress
• 🖼️ Cover Download: Download actual book cover images from Goodreads pages
• 🔍 Advanced Filtering: Filter by shelf, rating, year, reading status, and more
• ⚡ Fast Processing: Efficiently handles libraries of any size
• 🎯 Flexible Commands: Run individual commands or process everything at once

Installation

Prerequisites

• Go 1.24.4 or later
• A Goodreads library export CSV file

Building from Source

git clone <repository-url>
cd goodreads-tool
go build -o goodreads-tool main.go

Or use the provided Justfile:

just build

Quick Start

1. Export your Goodreads library:

   • Go to Goodreads → My Books → Import and Export
   • Click "Export Library" and save as goodreads_library_export.csv

2. Process your read books:

   ./goodreads-tool -cmd all -input goodreads_library_export.csv -shelf read
   

3. Find your generated files:

   • Obsidian notes: ./obsidian-books/
   • Analysis results: printed to console

Usage

Basic Commands

# Convert books to Obsidian notes
./goodreads-tool -cmd convert -input your_export.csv

# Analyze your library statistics
./goodreads-tool -cmd analyze -input your_export.csv

# Download book cover images
./goodreads-tool -cmd covers -input your_export.csv

# Run all commands
./goodreads-tool -cmd all -input your_export.csv

Command Options

Option	Description	Default
-cmd	Command to run: convert, analyze, covers, all	convert
-input	Path to Goodreads CSV export	goodreads_export.csv
-output	Output directory for generated files	obsidian-books
-shelf	Filter by bookshelf (e.g., read, currently-reading)	(all shelves)
-rating	Filter by minimum rating (1-5)	(all ratings)
-since	Filter by year (e.g., 2020)	(all years)
-status	Filter by reading status (read, reading, unread)	(all statuses)
-verbose	Show detailed output	false

Filtering Examples

# Process only books read since 2020
./goodreads-tool -cmd all -shelf read -since 2020

# Convert high-rated books (4+ stars)
./goodreads-tool -cmd convert -rating 4

# Analyze currently reading books
./goodreads-tool -cmd analyze -shelf currently-reading

# Process recent high-rated reads with verbose output
./goodreads-tool -cmd all -shelf read -since 2023 -rating 4 -verbose

Generated Content

Obsidian Notes

Each book generates a markdown note with:

---
parent: "[[Books read 2024]]"
author: "[[Author Name]]"
date: 2024-01-15
completed: 2024-03-20
tags:
- books
rating: 5
pages: 320
cover: "[[Book Title.jpg]]"
book-type:
book-series: "[[Series Name]]"
---
Add your review here!

Analysis Output

The analyze command provides:

• Reading Statistics: Total books, read vs. unread counts
• Rating Distribution: Breakdown by star rating
• Yearly Progress: Books read per year
• Top Rated Books: Your highest-rated reads
• Longest Books: Page count champions
• Reading Trends: Patterns in your reading habits

Cover Images

Downloads the main book cover image from each book's Goodreads page and saves them directly in the covers folder:

obsidian-books/
└── covers/
    ├── The Hunger Games.jpg
    ├── Pride and Prejudice.jpg
    ├── The Hobbit.jpg
    └── Another Book Title.jpg

Features:

• Simple Structure: Cover images saved directly with book title as filename
• Clean Filenames: Book titles are sanitized for cross-platform compatibility
• Optimal Size: Main book covers (typically ~350x500 pixels, ~30KB)
• Standard Format: All covers saved as .jpg files
• Automatic Linking: Generated markdown files include wiki-style references to cover images

Cover References in Markdown Files

When you run the convert command, each generated Obsidian note automatically includes a reference to its cover image:

---
parent: "[[Books read 2024]]"
author: "[[Suzanne Collins]]"
date: 2024-01-10T14:16:00
completed: 2024-03-15
tags:
- books
rating: 5
pages: 374
cover: "[[The-Hunger-Games.jpg]]"
book-type:
book-series:
---
Add your review here!

The cover: property uses Obsidian's wiki-link format to reference the corresponding cover image. When covers are downloaded with the covers command, Obsidian will automatically display the cover image when you view the note.

Complete Workflow:

1. Run ./goodreads-tool -cmd convert to generate markdown files with cover references
2. Run ./goodreads-tool -cmd covers to download the actual cover images
3. Open your vault in Obsidian to see books with their cover images displayed

Using with Just

This project includes a Justfile for common tasks:

# Most common workflows
just run-all-read                    # Process all read books
just run-all-read-since 2020        # Process reads since 2020
just convert-read-rated              # Convert 4+ star reads

# Specific commands
just analyze-read                    # Analyze read books
just convert-shelf currently-reading # Convert specific shelf
just covers-read-since 2023         # Generate covers for recent reads

# Development
just test                           # Run tests
just build                          # Build the tool
just help                           # Show all available commands

Filtering Guide

By Shelf

Goodreads organizes books into shelves. Common shelves include:

• read - Books you've finished
• currently-reading - Books you're reading now
• to-read - Books you want to read
• Custom shelves you've created

./goodreads-tool -cmd convert -shelf read

By Rating

Filter by minimum star rating (1-5):

./goodreads-tool -cmd analyze -rating 4  # 4+ star books only

By Year

Process books read or added since a specific year:

./goodreads-tool -cmd convert -since 2020  # Books since 2020

By Status

Filter by reading status:

• read - Completed books
• reading - Currently reading
• unread - Not yet started

./goodreads-tool -cmd analyze -status read

Combining Filters

Filters can be combined for precise control:

# High-rated books read since 2022
./goodreads-tool -cmd convert -shelf read -rating 4 -since 2022

# Currently reading books added this year
./goodreads-tool -cmd analyze -status reading -since 2024

Use Cases

For Obsidian Users

• Book Vault: Create a comprehensive book database in Obsidian with cover images
• Reading Journal: Track your reading progress and thoughts with visual book covers
• Book Recommendations: Link related books and authors with automatic cover display
• Series Tracking: Automatically detect and link book series
• Visual Library: Browse your books with cover images displayed in Obsidian

For Data Analysis

• Reading Habits: Analyze your reading patterns over time
• Goal Tracking: Monitor progress toward reading goals
• Preference Analysis: Understand your rating and genre preferences

For Library Management

• Inventory: Keep track of your book collection with cover images
• Backup: Create a local backup of your Goodreads data including covers
• Migration: Move data to other reading tracking systems
• Visual Organization: Browse your books by their actual covers

Troubleshooting

Common Issues

File not found error:

# Make sure your CSV file exists and path is correct
ls -la goodreads_library_export.csv
./goodreads-tool -input goodreads_library_export.csv

No books processed:

• Check your filters - they might be too restrictive
• Verify your CSV file has data
• Use -verbose flag to see detailed processing information

Permission errors:

# Ensure you have write permissions in the output directory
chmod 755 ./obsidian-books/

Getting Help

./goodreads-tool -h  # Show all available options
just help           # Show Justfile commands

Development

Running Tests

go test ./...
# or
just test

Project Structure

goodreads-tool/
├── main.go                 # Main application entry point
├── internal/
│   ├── analyzer/          # Library analysis functionality
│   ├── filter/            # Book filtering logic
│   ├── generator/         # File generation (Obsidian, covers)
│   ├── models/            # Data structures
│   ├── parser/            # CSV parsing
│   └── utils/             # Utility functions
├── Justfile               # Task runner commands
└── go.mod                 # Go module definition

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run the test suite: just test
5. Submit a pull request

License

[Add your license information here]

Acknowledgments

• Built for the Obsidian and Goodreads communities
• Inspired by the need for better book data management
• Thanks to all contributors and users providing feedback