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 <USER_ID> 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="<YOUR_USER_ID>"

Read Commands

1. View shelf

python3 $R shelf <USER_ID> --shelf <shelf> [--limit N] [--sort <sort>]

`--shelf`	Meaning
`currently-reading`	Currently reading
`read`	Already read
`to-read`	Want to read
`<custom>`	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 <USER_ID> --shelf currently-reading
python3 $R shelf <USER_ID> --shelf read --limit 20 --sort date_read
python3 $R shelf <USER_ID> --shelf to-read --limit 50
python3 $R shelf <USER_ID> --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 <USER_ID> [--limit N]

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

3. Search books

python3 $R search "<query>" [--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 <book_id>

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

5. Book reviews

python3 $R reviews <book_id> [--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 <book_id> <stars>

Stars: 1–5 (integer)

$W rate 40121378 5        # Rate Atomic Habits 5 stars

3. Change shelf

$W shelf <book_id> <shelf_name>

`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 <book_id>

Shortcut for shelf <book_id> currently-reading. RSS verified.

5. Finish reading

$W finish <book_id>

Shortcut for shelf <book_id> read. RSS verified.

6. Edit (dates, review, rating)

$W edit <book_id> [--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 <book_id> "<text>"

8. Update reading progress

$W progress <book_id> <page_or_percent>

⚠️ Book must be on currently-reading shelf.

$W progress 13618551 150    # Reading page 150

Sample Workflows

"What am I currently reading?"

python3 $R shelf <USER_ID> --shelf currently-reading

"Find books about Japanese history"

python3 $R search "Japanese history" --limit 10
# → get book_id → python3 $R book <id> 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.

goodreads

Goodreads Skill

Scripts

Setup