Goodreads CLI

Quick start

go install github.com/sameerbajaj/goodreads-cli/cmd/goodreads@latest
goodreads search "dune"
goodreads shelf set "Dune" --shelf currently-reading --rating 5 --yes

Why I built this

Goodreads deprecated their public developer API keys years ago. If you want to script reading list automations, extract book metadata into local text notes, or let an assistant update what you are reading, you are typically forced to use manual browser clicks.

I wanted a fast terminal client that could query book information, return structured JSON for shell pipelines, and write shelf changes back to Goodreads using an existing logged-in browser session.

Terminal commands and API workflows

Goodreads CLI provides terminal commands for book discovery, data extraction, and authenticated shelf mutations.

Extracting book metadata without API keys

Search books by title or author, pull ratings and genre classifications, and view review counts. Use the enrich command to merge book details into your own data formats with field selection flags like --select metadata.title,metadata.rating.

Updating reading shelves and star ratings

Update shelves directly from your terminal. Move books between to-read, currently-reading, and read, or clear them entirely. You can also assign 1 to 5 star ratings in the same command.

Connecting Goodreads to AI agents with MCP

Compile the included goodreads-mcp server to let Claude Desktop or Cursor look up book details and manage your reading list during conversations.

Reading browser session cookies automatically

On macOS, the tool can read active Goodreads session cookies directly from your local Brave or Chrome profile through Keychain. It decrypts the session in memory for the duration of the request, so you never have to manually copy session strings or store unencrypted passwords in dotfiles.

Automation scripts and shell pipelines

Every command supports --json for piping into jq or shell scripts. The --agent flag enables strict non-interactive formatting, disables terminal colors, requires explicit write confirmation, and redacts sensitive cookie strings from output.

How to install and authenticate

1. Install with Go (1.22+):

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

2. Verify your environment:

   goodreads doctor

3. Check authentication status:

   goodreads shelf auth-check

   If automatic browser detection is disabled, set your session manually via export GOODREADS_COOKIE="..." or configure ~/.config/goodreads-cli/config.toml.

Local security and privacy

The CLI accesses only Goodreads cookies from your local browser profile. Cookies are read locally through macOS Keychain, decrypted in memory, and never written to disk or sent to any server other than goodreads.com. There is no telemetry, tracking, or remote analytics.