Goodreads (Read + Write)

Goodreads Skill

Full read + write access to Goodreads via RSS feeds and Playwright browser automation.

Scripts

# Read-only (RSS + scraping, no login required)
R=scripts/goodreads-rss.py
Write (Playwright browser automation, requires one-time login)
W=scripts/goodreads-write.sh

Setup

See references/SETUP.md for installation and first-time login instructions.

Quick start:

# Install dependencies
pip install playwright playwright-stealth
playwright install chromium
Login to Goodreads (one-time, opens browser)
./scripts/goodreads-write.sh login

User Configuration

Replace with your Goodreads user ID in all commands below.

> How to find your user ID: Go to your Goodreads profile page. The URL will be like: > goodreads.com/user/show/12345678-yourname — the number is your user ID.

For write commands with RSS verification, set:

export GOODREADS_USER_ID=""

Read Commands

1. View shelf

python3 $R shelf  --shelf  [--limit N] [--sort ]

| --shelf | Meaning | |---|---| | currently-reading | Currently reading | | read | Already read | | to-read | Want to read | | | Custom shelf |

| --sort | Meaning | |---|---| | date_read | Date finished (default for read) | | date_added | Date added to shelf | | rating | Personal rating | | title | Book title | | author | Author name | | avg_rating | Average Goodreads rating |

Examples:

python3 $R shelf  --shelf currently-reading
python3 $R shelf  --shelf read --limit 20 --sort date_read
python3 $R shelf  --shelf to-read --limit 50
python3 $R shelf  --shelf read --limit 200 --sort rating

Fields returned: title, author, book_id, isbn, user_rating (0–5), average_rating, date_read, date_added, review, shelves, description (300 chars), published, book_url

2. Recent activity

python3 $R activity  [--limit N]

Returns: books added, marked read, reviews written...

3. Search books

python3 $R search "" [--limit N]

python3 $R search "Jared Diamond" --limit 10
python3 $R search "atomic habits" --limit 5

Returns: book_id, title, author, book_url

4. Book details

python3 $R book 

Returns: title, author, average_rating, rating_count, review_count, description, isbn, published, genres, image_url

5. Book reviews

python3 $R reviews  [--limit N]

> ⚠️ Reviews are rendered via React — available count may be limited.

Write Commands

> Requires one-time login. Run $W login first. Session persists for weeks/months.

1. Check login status

$W status

2. Rate a book

$W rate  

Stars: 1–5 (integer)

$W rate 40121378 5        # Rate Atomic Habits 5 stars

3. Change shelf

$W shelf  

| shelf_name | Display | Notes | |---|---|---| | to-read | Want to Read | | | currently-reading | Currently Reading | | | read | Read | |

Output includes "verified": true/false — RSS auto-confirms after action.

$W shelf 186190 read                # Move to "Read"
$W shelf 186190 currently-reading   # Move to "Currently Reading"

4. Start reading

$W start 

Shortcut for shelf currently-reading. RSS verified.

5. Finish reading

$W finish 

Shortcut for shelf read. RSS verified.

6. Edit (dates, review, rating)

$W edit  [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--stars N] [--review "text"]

Uses the /review/edit/ page — can edit everything in one command.

> ⚠️ Book must be shelved first (use $W shelf or $W start).

Examples:

$W edit 186190 --start-date 2025-01-15 --end-date 2025-02-20
$W edit 186190 --stars 4
$W edit 186190 --review "Great book, highly recommend."
$W edit 186190 --start-date 2025-03-01 --end-date 2025-03-08 --stars 4 --review "Updated review"

7. Write/Update review

$W review  ""

8. Update reading progress

$W progress  

> ⚠️ Book must be on currently-reading shelf.

$W progress 13618551 150    # Reading page 150

Sample Workflows

"What am I currently reading?"

python3 $R shelf  --shelf currently-reading

"Find books about Japanese history"

python3 $R search "Japanese history" --limit 10
→ get book_id → python3 $R book  for details

"I just finished Forrest Gump, rate 4 stars, read from 3/1 to 3/8"

$W finish 186190
$W edit 186190 --stars 4 --start-date 2025-03-01 --end-date 2025-03-08

"Start reading Atomic Habits"

$W start 40121378

Output Format

All commands return JSON:

{
  "success": true,
  "action": "edit",
  "book_id": "186190",
  "changes": ["start_date=2025-03-01", "end_date=2025-03-08", "stars=4"],
  "message": "Updated: start_date=2025-03-01, end_date=2025-03-08, stars=4"
}

Limitations

| Feature | Status | |---|---| | Read shelf | ✅ RSS, max 200 books/request | | Activity feed | ✅ RSS | | Search books | ✅ Scraping | | Book details | ✅ Scraping + JSON-LD | | Reviews | ⚠️ Limited scraping | | Rate (1-5 stars) | ✅ | | Change shelf (+ RSS verify) | ✅ | | Start/Finish reading | ✅ | | Write/edit review | ✅ | | Edit reading dates | ✅ | | Update progress | ✅ (requires currently-reading) | | Session persistence | ✅ (stealth, weeks/months) | | Remove from shelf | ❌ Not supported | | Custom shelves (write) | ❌ Only 3 main shelves |

> Note: Goodreads may change its UI → scripts may break. If errors occur, check selectors. > Anti-bot: Uses playwright-stealth + --disable-blink-features=AutomationControlled.

See references/SETUP.md for installation and first-time login instructions.

Quick start:

# Install dependencies
pip install playwright playwright-stealth
playwright install chromium
Login to Goodreads (one-time, opens browser)
./scripts/goodreads-write.sh login