Goodreads Tools (unofficial)
A pragmatic, scriptable CLI that turns your Goodreads shelves into dashboard-ready data. It exports clean JSONL for your reading timeline (including rereads), estimates pages per day, and renders a text-based bar chart you can use in a terminal or CI logs.
What it does
- Export your reading timeline with start/end dates and page counts.
- Generate pages-per-day charts from that timeline (even with overlapping reads).
- Pull book metadata and public shelf data without needing API keys.
- Keep everything scriptable with JSON/CSV output.
How it works
- Public data comes from Goodreads RSS feeds and book pages.
- For read-start/end dates, the CLI scrapes the public review list HTML (the
readshelf exposes those fields). - Page counts come from RSS when available and fall back to book pages if needed.
- Auth helpers exist for future write operations, but are not required for read-only features.
Sample: last 10 finished books (read shelf)
| Title | Started | Finished | Pages | Book ID |
|---|---|---|---|---|
| A Christmas Carol | 2025-12-22 | 2025-12-30 | 184 | 5326 |
| A Philosophy of Software Design | 2025-08-01 | 2025-12-30 | 184 | 58665335 |
| The Wright Brothers | 2025-10-13 | 2025-10-14 | 320 | 22609391 |
| The Secret of Our Success: How Culture Is Driving Human Evolution, Domesticating Our Species, and Making Us Smarter | 2025-09-15 | 2025-10-10 | 456 | 25761655 |
| Kill It with Fire: Manage Aging Computer Systems | 2025-09-27 | 2025-10-07 | 248 | 54716655 |
| The Almanack of Naval Ravikant: A Guide to Wealth and Happiness | 2025-09-25 | 2025-10-05 | 244 | 54898389 |
| The Thinking Machine: Jensen Huang, Nvidia, and the World's Most Coveted Microchip | 2025-09-05 | 2025-09-12 | 272 | 211399783 |
| Influence: The Psychology of Persuasion | 2025-07-30 | 2025-09-06 | 320 | 28815 |
| Think Again: The Power of Knowing What You Don't Know | 2025-06-12 | 2025-07-22 | 307 | 55539565 |
| Getting Naked: A Business Fable about Shedding the Three Fears That Sabotage Client Loyalty | 2025-07-01 | 2025-07-07 | 240 | 7717531 |
More sample outputs live in samples/README.md.
Quick start
# search titles
uv run goodreads-tools public search "Dune" -n 5
# export a reading timeline as JSONL
uv run goodreads-tools public shelf timeline --user <user-id> --shelf read --source html --format jsonl
# HTML scraping is concurrent by default; use --concurrency 1 to opt out
uv run goodreads-tools public shelf timeline --user <user-id> --shelf read --source html --format jsonl --concurrency 1
# render a pages/day chart for a date range
uv run goodreads-tools public shelf chart --user <user-id> --shelf read --source html --from 2023-01-01 --to 2025-12-30 --bin-days 14
Development
# create / activate the project environment
uv sync
# run the dev CLI
uv run goodreads-tools
# run via uvx (local)
uvx --from . goodreads-tools --help
# run via uvx (git)
uvx --from git+https://github.com/EvanOman/goodreads-tools goodreads-tools --help
# run unit tests
uv run pytest
# run live tests (network)
GOODREADS_LIVE=1 uv run pytest -m live
# justfile helpers (lint/type/test)
just lint
just type
just test
Releases
Releases use release-please with conventional-commit PR titles. It maintains a single
release PR on master; when you merge that PR, it creates the tag and GitHub Release.
The PyPI publish job runs on the GitHub Release (best-effort until OIDC is configured).
See docs/RELEASE.md for the full flow and examples.
The project targets Python 3.13 (via .python-version). Use uv for dependency management and execution.
1 maintainer
Metadata
1 maintainer
Release files for goodreads-tools 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| goodreads_tools-1.2.0.tar.gz | 15.5 kB | With provenance | Details for goodreads_tools-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| goodreads_tools-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for goodreads_tools-1.2.0-py3-none-any.whl |
Total release size: 37.2 kB
Release files / goodreads_tools-1.2.0.tar.gz
| Download URL | goodreads_tools-1.2.0.tar.gz |
|---|---|
| Size | 15.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36c8905308c1e484d924fc57510e6341251479e9ff784f9ba462c7fa644e375d
|
|
BLAKE2b-256 checksum How to use checksums |
1de2f282f04c8af1520f8bfba6a68ae20762e0f82ae75c2c0b85fa9f65d8bf7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 3, 2026.
Transparency logRelease files / goodreads_tools-1.2.0-py3-none-any.whl
| Download URL | goodreads_tools-1.2.0-py3-none-any.whl |
|---|---|
| Size | 21.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6f910bd51a6a7c16f231a52f67b66266882ed3a61bcc73b6667df782d79c0bb2
|
|
BLAKE2b-256 checksum How to use checksums |
be968fccdcd50bad99d13cb6559924cc20e62bb88838a47eb7536678df45afe6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 3, 2026.
Transparency logSecurity for goodreads-tools 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for goodreads_tools-1.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
