# Goodreads CLI (`goodreads`)

[![Go Reference](https://pkg.go.dev/badge/github.com/sameerbajaj/goodreads-cli.svg)](https://pkg.go.dev/github.com/sameerbajaj/goodreads-cli)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Author](https://img.shields.io/badge/Author-Sameer%20Bajaj-blue.svg)](https://sameerbajaj.com)
[![Tools](https://img.shields.io/badge/Tools-sameerbajaj.com%2Ftools-blue.svg)](https://sameerbajaj.com/tools)

A command-line tool and MCP server for Goodreads book search, metadata extraction, and authenticated shelf/rating write-back, built by [Sameer Bajaj](https://sameerbajaj.com).

It uses public Goodreads pages for read-only metadata and the logged-in Goodreads web GraphQL endpoint for shelf changes. Goodreads no longer issues new public API keys, so authenticated writes use your own browser session, `GOODREADS_COOKIE`, or `GOODREADS_JWT`.

## Install

```bash
go install github.com/sameerbajaj/goodreads-cli/cmd/goodreads@latest
```

Verify:

```bash
goodreads doctor
goodreads --help
```

## Quick Start

```bash
goodreads search dune
goodreads book 44767458-dune --json
goodreads enrich "Dune" --json --select metadata.title,metadata.rating,metadata.ratings_count
```

## Shelf Write-Back

On macOS, `goodreads` can use your local Brave or Chrome Goodreads cookies automatically. It reads only Goodreads cookies, decrypts them locally through Keychain, and does not print or store them.

```bash
goodreads shelf auth-check --json
goodreads shelf set --book-id 44767458-dune --shelf currently-reading --yes --json
goodreads shelf set "Dune" --shelf read --rating 5 --tags sci-fi,classics --yes --json
goodreads shelf rate --book-id 44767458-dune --rating 5 --yes --json
goodreads shelf unrate --book-id 44767458-dune --yes --json
goodreads shelf unshelve --book-id 44767458-dune --yes --json
```

Supported shelves are `to-read`, `currently-reading`, and `read`; aliases include `want-to-read`, `reading`, `completed`, and `done`.

Started/finished date writes are intentionally rejected for now because the current Goodreads web client did not expose a verified date mutation.

## Auth Options

Automatic macOS browser auth tries Brave first, then Chrome. You can force a browser or disable auto browser auth:

```bash
GOODREADS_BROWSER=brave goodreads shelf auth-check --json
GOODREADS_BROWSER=chrome goodreads shelf auth-check --json
GOODREADS_NO_BROWSER_AUTH=1 goodreads shelf auth-check --json
```

Manual auth also works:

```bash
export GOODREADS_COOKIE='_session_id2=...; other_cookie=...'
goodreads shelf auth-check --json

export GOODREADS_JWT='...'
goodreads shelf auth-check --json
```

You can store config at `~/.config/goodreads-cli/config.toml`:

```toml
goodreads_browser = "brave"
# or:
goodreads_cookie = "_session_id2=...; other_cookie=..."
# or:
goodreads_jwt = "..."
```

## Agent Usage

The CLI is designed for LLM and automation use:

- `--agent` sets JSON, compact output, non-interactive mode, no color, and `--yes`.
- `--dry-run` previews writes without sending them.
- Mutating commands are grouped under `shelf`.
- Write commands require `--yes` unless `--dry-run` is used.
- Secrets are redacted from dry-run output.

Example for another LLM or local agent:

```bash
goodreads shelf set "The Left Hand of Darkness" --shelf currently-reading --agent
goodreads enrich "The Left Hand of Darkness" --agent --select metadata.title,metadata.rating,metadata.ratings_count,book_id
```

## MCP

Build the MCP server:

```bash
go build -o bin/goodreads-mcp ./cmd/goodreads-mcp
```

Manual Claude Desktop config:

```json
{
  "mcpServers": {
    "goodreads": {
      "command": "goodreads-mcp"
    }
  }
}
```

## Commands

```bash
goodreads search "left hand of darkness"
goodreads book 44767458-dune --json
goodreads author 58.Frank_Herbert --json
goodreads review <user_id> --json
goodreads enrich "Dune" --json
goodreads shelf auth-check --json
```

Run `goodreads <command> --help` for command-specific flags.

## Build From Source

```bash
git clone https://github.com/sameerbajaj/goodreads-cli.git
cd goodreads-cli
go test ./...
go build -o bin/goodreads ./cmd/goodreads
```

## Notes

This project was initially scaffolded with a CLI generator, then customized for Goodreads' current public web and logged-in web behavior.

---

## 👤 Author

Developed by [Sameer Bajaj](https://sameerbajaj.com), a Product Manager & Software Builder. Explore more developer tools at [sameerbajaj.com/tools](https://sameerbajaj.com/tools).

---

## 📄 License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.