pp-goodreads

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/goodreads/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Goodreads — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `goodreads-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install goodreads --cli-only
   ```
2. Verify: `goodreads-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/goodreads/cmd/goodreads-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints and sends the configured Goodreads session as the `_session_id2` cookie. It does not require a resident browser process for normal API calls.

## MCP Surface

The MCP binary defaults to stdio and can serve streamable HTTP for hosted agents:

```bash
goodreads-pp-mcp
goodreads-pp-mcp --transport http --addr :7777
```

Default MCP registration exposes `goodreads_search` and `goodreads_execute` for the full route map, plus local `search`, `sql`, and `context`. Raw endpoint mirror tools are opt-in with `GOODREADS_MCP_ENDPOINT_MIRRORS=1`. Mutating routes remain blocked unless `GOODREADS_PP_ALLOW_WRITES=1` is set after explicit approval.

## Command Reference

**amazon-purchases** — Manage amazon purchases

- `goodreads-pp-cli amazon-purchases` — Amazon purchases import/inspection page.

**book** — Manage book

- `goodreads-pp-cli book <book_slug>` — Book detail page. Current page is Next.js-backed.

**comment** — Manage comment

- `goodreads-pp-cli comment <user_slug>` — User comments/recent posts page.

**feed** — Read the home updates feed (friends' activity)

- `goodreads-pp-cli feed list` — Read the home updates feed (friends' activity). Use `--page <n>` to walk older activity. Read-only POST to `/home/load_more_updates`.

**friend** — Explore Goodreads friends and friend requests

- `goodreads-pp-cli friend list` — Friends index page.
- `goodreads-pp-cli friend list-requests` — Friend requests page.

**genres** — Browse Goodreads genre and shelf discovery pages

- `goodreads-pp-cli genres get` — Genre landing page.
- `goodreads-pp-cli genres list` — Genre index page.
- `goodreads-pp-cli genres list-list` — Alphabetical genre shelves index.
- `goodreads-pp-cli genres list-search` — Genre finder route.

**giveaway** — Browse and enter Goodreads Giveaways

- `goodreads-pp-cli giveaway list` — Browse the Goodreads Giveaways listing (`--format`, `--genre`).
- `goodreads-pp-cli giveaway show <giveaway_id>` — Show one giveaway detail page.
- `goodreads-pp-cli giveaway enter <giveaway_id>` — Enter a giveaway. NOT YET LIVE: the entry POST shape was not captured; live execution is refused, `--dry-run` previews the best-known request.

**goodreads-web-undocumented-search** — Manage goodreads web undocumented search

- `goodreads-pp-cli goodreads-web-undocumented-search` — Canonical book search route from OpenSearch descriptor.

**list** — Manage list

- `goodreads-pp-cli list <list_id>` — Public Listopia list page.

**message** — Inspect and plan Goodreads message-folder actions

- `goodreads-pp-cli message create` — Batch message folder/read action.
- `goodreads-pp-cli message get` — User message folder page.
- `goodreads-pp-cli message get-show` — Message detail page.
- `goodreads-pp-cli message list` — User message inbox.
- `goodreads-pp-cli message list-markallasread` — Mark all visible inbox messages read.

**notes** — Read and plan Kindle notes/highlights actions

- `goodreads-pp-cli notes get` — User Kindle Notes & Highlights index.
- `goodreads-pp-cli notes get-bookslug` — Notes/highlights detail page for one book and user.

**notifications** — Inspect Goodreads notifications and tracking calls

- `goodreads-pp-cli notifications create` — Notification tracking call emitted by the UI.
- `goodreads-pp-cli notifications list` — User notifications page.

**opensearch-xml** — Manage opensearch xml

- `goodreads-pp-cli opensearch-xml` — OpenSearch descriptor for Goodreads book search.

**quotes** — Read Goodreads quotes and quote widgets

- `goodreads-pp-cli quotes get` — User quotes widget script.
- `goodreads-pp-cli quotes list` — Current user's quotes list.

**rating** — Set or clear your star rating for a book (GraphQL)

Ratings are written through the modern Goodreads AWS AppSync GraphQL API (`RateBook` / `UnrateBook`), not a legacy form. They need a bound AppSync JWT — a different credential from the session cookie. Set it via `GOODREADS_GRAPHQL_TOKEN` (see Auth Setup). Writes are gated: `--dry-run` to preview, or `GOODREADS_PP_ALLOW_WRITES=1` after approval to execute.

- `goodreads-pp-cli rating set <book_id> --stars <1-5>` — Rate a book (RateBook GraphQL mutation).
- `goodreads-pp-cli rating clear <book_id>` — Clear your rating (UnrateBook GraphQL mutation).

**recommendations** — Inspect Goodreads recommendation pages

- `goodreads-pp-cli recommendations list` — Personalized recommendations page.
- `goodreads-pp-cli recommendations list-tome` — Friends' recommendations page.

**review** — Read and write reviews; plan bookshelf/review table actions

- `goodreads-pp-cli review create <book_id>` — Write/update a review for a book (`--review`, `--spoiler`, `--publicize`, `--add-to-blog`, `--shelf`, `--notes`). Posts the legacy `/review/update/:book_id` form (form-urlencoded). The Rails CSRF token comes from the `GOODREADS_AUTHENTICITY_TOKEN` env var or stdin (the `--authenticity-token` flag is deprecated — it leaks into shell history / `ps aux`). Star ratings are GraphQL-only — use `rating set`.
- `goodreads-pp-cli review create-update <book_id> --stdin` — Inline review/date/notes field update for one book. Pipe a JSON object of Rails review form fields (e.g. `{"review[review]":"..."}`); sent form-urlencoded to `/review/update/:book_id`. CSRF token via `GOODREADS_AUTHENTICITY_TOKEN`.
- `goodreads-pp-cli review create-updatelist` — Batch update selected reviews/books on a user's shelf table.
- `goodreads-pp-cli review get` — Bookshelf list for a user, optionally filtered by shelf.
- `goodreads-pp-cli review get-listrss` — This public XML route is the cleanest current read API for shelf exports.
- `goodreads-pp-cli review get-stats` — Reading stats page.
- `goodreads-pp-cli review list` — Review drafts page.
- `goodreads-pp-cli review list-duplicates` — Duplicate books tool.
- `goodreads-pp-cli review list-import` — Import/export page.

**shelf** — Inspect and plan Goodreads shelf operations

- `goodreads-pp-cli shelf create` — Add or remove one book from a shelf through the shelf chooser helper.
- `goodreads-pp-cli shelf create-movebatch` — Reorder books/shelves in batch.
- `goodreads-pp-cli shelf create-movebatch-2` — Persist shelf-table position changes for a user.
- `goodreads-pp-cli shelf create-movetoposition` — Move one shelf/book row to a specific position.
- `goodreads-pp-cli shelf create-removebook` — Remove one book from a shelf from the button helper.
- `goodreads-pp-cli shelf create-update` — Update shelf display/settin