Install

uv tool install great

Quick Start

Bootstrap a data repo and try the loop locally:

mkdir my-media && cd my-media
great init                                       # seeds one list per kind
great want "Severance" --kind tv                 # queue what you haven't watched
great consumed "The Godfather" --kind movie      # catalog + diary + focused rank
great consumed "Severance"                       # promotes the wanted item in
great rank movies                                # broader ranking pass when you want
great rank tv --want                             # rank watch-next priorities
great build                                      # render → dist/

A working sample lives in examples/sample-data/. great init (default --with-pages) drops a GitHub Actions workflow that builds the site and deploys to Pages on every push.

CLI

great init [PATH] [--list NAME:KIND]... [--with-pages]

Bootstrap a data repo (drops a Pages-deploy workflow by default).

great lists

Show configured lists.

great rank <list> / great rank <kind> --want

Run a Textual ranking session — over a favorite-list, or (with --want) the want queue for <kind>. Filters: --recent N seeds clusters from the last N diary entries to place them in the broader ranking; --by CREATOR and --from PARENT hard-restrict the universe (rank Beatles albums against each other, songs from an album, episodes from a podcast).

great show <list> / great show <kind> --want

Print the inferred ranking, favorites or want.

great consumed <item> [--kind KIND] [--at DATE] [--notes ...] [--no-log] [--no-rank]

Mark an item as consumed. Catalogs it if new (--kind required for brand-new titles), promotes it from the want queue if wanted, writes a diary entry, and runs a focused ranking session for newly-cataloged items. --no-log skips the diary; --no-rank skips ranking. Already-cataloged items get a diary row only — use great rank to re-rank them.

great started <item> [--kind KIND] [--at DATE] [--notes ...]

Log that you’ve started an item; catalog it if new. Never promotes from the want queue or ranks (no opinion formed yet).

great abandoned <item> [--kind KIND] [--at DATE] [--notes ...]

Log that you’ve abandoned an item; catalog it if new. Never promotes or ranks.

great log <item> [--status ...] [--notes ...] [--at DATE]

Low-level diary append for items already in the catalog or want queue. Useful for backfilling; never auto-creates, never ranks.

great want <title> --kind KIND [--year YEAR] [--id ID]

Add a free-form title to the kind’s want queue (one queue per kind).

great unwant <item> [--kind KIND]

Remove from the kind’s want queue.

great import spotify <path>

Import a Spotify Extended Streaming History folder (the unzipped privacy-portal export, with Streaming_History_Audio_*.json inside). Each unique track becomes a song item, each unique album becomes an album item, and every (track, day) the user actually completed (trackdone or ≥ 30s played) synthesizes a consumed diary entry.

great build [--out dist/]

Render the static site.

Development

uv sync
uvx nox            # runs all default sessions
uvx nox -s tests   # just tests
uvx nox -s style   # ruff check + format
uvx nox -s typing  # ty