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 copy your API token from Account Settings.

oku auth set-token  # Save your Hardcover API token
oku sync            # Pull your library into the local cache
oku                 # Launch the dashboard

Your token is stored in the system keychain. You can also set HARDCOVER_TOKEN, which takes priority over the 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.

Key	What it does
1–5	Jump to a tab
h / l	Previous / next tab
Tab / Shift+Tab	Previous / next tab
j / k	Navigate lists, scroll the detail pane and the stats page
Enter	Open the selection in the detail pane (Esc goes back)
+ / -	Quick page update
u	Set an exact page
U	Undo the last change while its toast is visible
/	Search
Ctrl+T / m	Cycle the search mode: Title, Author, Genre
? / q	Help / quit

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.

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:

theme	What you get
auto (default)	the built-in palette, for whichever background the terminal reports
dark, light	the built-in palette with a dark or light dashboard background
nord	Nord
tokyo-night	Tokyo Night (night)
dracula	Dracula
gruvbox-dark, gruvbox-light	Gruvbox
solarized-dark, solarized-light	Solarized
catppuccin-mocha	Catppuccin Mocha

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.