oku

Oku

Your Hardcover library in your terminal. Browse your shelves, find your next book, and track your reading with a keyboard-driven dashboard or quick CLI commands.

The recording uses fictional books and sample reading data. Recording instructions.

Install and run

On macOS, install with Homebrew:

brew tap Kameleon21/oku
brew install --cask oku

For Linux and Windows, download and extract a prebuilt archive from GitHub Releases and add the oku binary (oku.exe on Windows) to your PATH.

Alternatively, install from source with Go 1.25.7 or later:

go install github.com/Kameleon21/oku/cmd/oku@latest

Make sure Go's binary directory (usually ~/go/bin) is on your PATH. Run oku --version to check your version.

Connect Hardcover

Create an account at hardcover.app, then sign in:

oku auth login  # Sign in via your browser
oku sync        # Pull your library into the local cache
oku             # Launch the dashboard

oku auth login opens Hardcover in your browser to approve access, then stores the resulting token in your system keychain; it's refreshed automatically as needed. Run oku auth status to check who you're signed in as and how, and oku auth logout to sign out and revoke it.

No browser handy (e.g. over SSH)? Run oku auth set-token instead: it prints a link to Hardcover's "New API Key" form with the scopes oku needs already checked, so you just name the key and paste it in. HARDCOVER_TOKEN also works as an env var and takes priority over any saved token.

Everyday use

Browse reading lists, search by book, author, or genre, and update your progress without leaving the terminal. The dashboard also shows your Hardcover reading goal, yearly summary, activity heatmap, ratings, and genre breakdowns.

oku reading                          # Currently reading
oku finished                         # Finished books
oku search "Ursula K. Le Guin" --mode author
oku update --book 123 --page +10      # Add 10 pages to a book's progress
oku stats                            # Reading stats and activity heatmap
oku sync                             # Refresh cached Hardcover data

Replace 123 with a book ID from your library. You can omit --book when there is exactly one active book. --page accepts an absolute page number or a relative change such as +10 or -5.

Use --json on commands that support structured output, such as oku reading --json. Set --view compact|default|verbose to adjust output density. Run oku --help or oku <command> --help for all commands and flags.

Dashboard controls

Launch with oku or oku tui. The dashboard has five tabs — Reading, Oku, Search, Stats and Timer — named in the strip along the top. Navigation uses vim-style keys; arrow keys also work.

On a terminal at least 100 columns wide the detail pane sits beside the list; below that Enter opens it in place of the list. In the Search tab Enter opens a result the same way, and a adds it to Reading. Press ? for every control the focused tab understands.

In Stats, press b to browse the books behind this year's finished count, newest completion first. Rereads appear separately, matching the stats total. Use j/k to select a book and Enter for its details. Press n to write or edit a private note stored only on this device, or v to save a rating and review to Hardcover. Ctrl+S saves either form; Esc cancels. From details, Esc returns to the finished list; another Esc returns to the stats charts. Private notes work offline and survive library syncs; they are not uploaded to Hardcover. The existing n note/quote action on Reading and Oku remains a Hardcover journal entry using your account's privacy setting.

The Search tab has two states and no modes. / puts the cursor in the query, where every key is a character — Ctrl+T cycles Title/Author/Genre, Enter searches, Esc goes back to the tab you came from. Esc or i over the results puts it back in the query; there m cycles the mode and j/k, Enter and a work as they do in the other lists.

Journals, goals, discovery and library transfer

Write notes and quotes with oku note / oku quote, edit reading goals with oku goals set, inspect rich book details with oku book, discover books with oku trending, and transfer your library with oku export / oku import. Imports preview changes by default, including Goodreads CSV matching by ISBN.

In the dashboard: n opens a note/quote editor, p pauses a book, P toggles Reading's paused shelf, J/K reorder the Oku queue, R refreshes that queue, and Ctrl+D in the Search input (Shift+D in results) loads trending books. Enter loads rich details and your journal.

See reader tools for commands, privacy, ranking and import behavior.

Reading timer

Track time spent reading with local sessions:

oku timer start     # Choose a currently reading book
oku timer status    # Check elapsed time
oku timer stop      # Save the session
oku timer stats     # Review reading time

Timer sessions are stored locally, separately from your Hardcover reading stats.

Configuration

Run oku config edit to open your settings, or oku config show to see the configuration and data paths. On macOS and Linux, the default configuration file is ~/.config/oku/config.toml; on Windows it is %AppData%\oku\config.toml. XDG_CONFIG_HOME overrides the configuration directory. Existing Windows installations may continue using the legacy ~/.config/oku/config.toml file.

editor = "nvim"
use_fzf = false
default_list = "reading"
theme = "auto" # auto | dark | light | a named palette

Themes

Press T in the dashboard to choose a theme. Type to filter the list, use ↑/↓ (or Ctrl+n/Ctrl+p, Tab/Shift+Tab) to preview it live, then press Enter to save it for future runs. Esc restores your previous theme. While typing in a search or filter field, leave the field first with Esc.

The dashboard and colored CLI output adapt to light and dark terminals. Set theme explicitly if your terminal reports its background incorrectly, or name a palette to use it instead of the built-in one:

Names are matched case-insensitively and an underscore reads as a hyphen, so Tokyo_Night works too. Named palettes include their own dashboard background, which changes along with the text and panels during live preview. auto keeps your terminal's background. Themes color Oku's screen without changing your terminal's color settings.

oku config theme                # list the values, marking the one in use
oku config theme --preview      # draw a swatch of every palette
oku config theme nord --preview # draw just that one
oku config theme nord           # write it to the config file

When a palette is named, the dashboard's help modal titles itself with it (Help · nord), so a screenshot says which scheme it was taken in. A theme value that is not one of these stops the coloured commands from starting, and is reported by oku config show; oku config itself always runs, so the value can be found and replaced.

NO_COLOR is supported; borders and a ▸ marker also indicate focus.

Oku caches library data in SQLite and refreshes it automatically. Run oku sync for a full refresh, or use oku reading --refresh to refresh a reading list.

Contributing

Use the Go version specified in go.mod, then run:

go test ./...
go vet ./...
go build ./cmd/oku

Open feature pull requests against develop. See the development and release guide for the branch workflow and release steps. To try the development version:

go install github.com/Kameleon21/oku/cmd/oku@develop

License

MIT.