# Command line `libbui` with no command opens the interface. The commands below do the same things from scripts. Results go to standard output: a table for people, or JSON with `--json` for programs. Notes, prompts and progress go to standard error, so piping stays clean. | Command | Does | | --- | --- | | `libbui pair [CODE]` | Pair with a setup code. Without `CODE` it is read from the terminal, which keeps it out of your shell history. | | `libbui unpair [--yes]` | Forget the pairing on this computer. Asks first; `--yes` when not in a terminal. | | `libbui loans [--card CARD]` | Your loans, with due dates and what can be downloaded. | | `libbui holds [--card CARD]` | Your holds and your place in line. | | `libbui cards` | Your library cards and how much of each limit is used. | | `libbui search QUERY… [--kind ebook\|audiobook\|magazine] [--available] [--library KEY \| --all-libraries] [--limit N] [--page N]` | Search a library's catalogue. Defaults to `default_library`, then your first card's library. `--all-libraries` searches every library linked to your cards. | | `libbui borrow TITLE_ID [--card CARD]` | Borrow a title. | | `libbui return TITLE_ID [--card CARD]` | Return a loan early. | | `libbui renew TITLE_ID [--card CARD]` | Renew a loan. | | `libbui hold TITLE_ID [--card CARD]` | Place a hold. | | `libbui download TITLE_ID… \| --all [--card CARD] [--format ID] [--dir PATH] [--force]` | Download loans that are offered as files (see above). Formats libbui does not support are listed and skipped. Books already in your library are skipped unless `--force`. | | `libbui compare TITLE_ID… [--library KEY]…` | Availability and estimated waits for up to 24 titles at each of your libraries. | | `libbui sample TITLE_ID [--library KEY] [--format ID] [--open]` | Print or open a title's publisher sample without borrowing it. | | `libbui tag list \| show \| create [--wishlist] \| rename \| delete \| add \| remove` | Your own tags and wishlists, kept on this device. | | `libbui cloud-tag list \| show \| create \| rename \| delete \| add \| remove` | Read and edit the tags in your Libby account. | | `libbui history list \| set --state STATE \| observe \| export [--format FORMAT] \| import FILE [--time-zone IANA_ZONE]` | Your reading history and reading states, kept on this device. | | `libbui follow list \| add title\|author\|series \| remove` | Follow titles, authors and series for notices. | | `libbui notices list [--unread] \| refresh [--library KEY] \| read` | Notices about holds and what you follow, checked only when you ask. | | `libbui magazine list \| subscribe \| unsubscribe \| issues` | Magazine subscriptions and back issues. | | `libbui annotations list \| import FILE [--format FORMAT] \| export [--format FORMAT]` | Highlights, notes and bookmarks from Libby's Reading Journey. | | `libbui paths` | Where libbui keeps its files. | | `libbui config init [--force] \| show \| path` | Write a commented configuration file, show the one in effect, or print its path. | | `libbui completions SHELL` | Completion script for bash, zsh, fish, elvish or powershell. | | `libbui doctor [--online]` | Check the terminal, configuration and pairing. Makes no request unless `--online` (then exactly one sync). | | `libbui adobe reset [--json]` | Forget an interrupted Adobe registration so the next download registers again at once. A finished registration is never touched. | `CARD` is a card id or a library key, as listed by `libbui cards`. Every command that takes a title id accepts the ids printed by `loans`, `holds` and `search`. Global options work before or after the command: `--config FILE`, `--lang TAG`, `--log FILTER`, `--no-color` (or `NO_COLOR=1`) and `--sample-library`. The interface also takes `--theme NAME`, `--ascii` and `--no-mouse`. Each has an environment variable: `LIBBUI_CONFIG`, `LIBBUI_LANG`, `LIBBUI_LOG`, `LIBBUI_SAMPLE_LIBRARY`, `LIBBUI_THEME`. `download` shows a progress line per book on a terminal and one plain line per event otherwise. `Ctrl-c` pauses what is in flight; running the same command again resumes it. ## JSON output Commands with `--json` write one JSON value to standard output, followed by a newline; messages go to standard error. The records are defined by the command line itself, not copied from Libby's responses or libbui's files, so an internal change cannot reshape them. Snapshot tests hold each one in place. - Field names, types, enum spellings and the shape of arrays and objects only change in a release that says so. New fields may appear: ignore what you do not know. - Catalog title IDs, card IDs and library keys are strings. libbui's own tag, follow and notice IDs are integers. - Times are RFC 3339 strings in UTC, such as `2026-11-15T12:00:00Z`. - Field names are snake_case. A value that is unknown or unset is `null`, except in `compare`, whose availability figures appear only when the library reports them. - History events carry their `kind` as a string. A `reading_state` event adds `state`; an `imported` one adds `metadata`, Libby's own record as JSON text. - `cloud-tag` records keep Libby's camelCase names and pass through the properties Libby adds, since they describe Libby's own tags. - `history export` and `annotations export` are interchange files with their own versioned formats, not `--json` records. ## Sample library `--sample-library` runs a command against a built-in library: two cards, a shelf, holds, a catalogue, Libby tags and a little reading history. It needs no account and no network, and nothing is saved. Read-only commands work; pairing, borrowing, downloads and other changes are refused. Try: ```sh libbui --sample-library loans libbui --sample-library search dune --json ``` ## Exit codes | Code | Meaning | | --- | --- | | 0 | Success. Also when a reader of the output closes the pipe early (`libbui loans \| head`). | | 1 | Failure: Libby refused, the network failed, a download failed, nothing was downloadable. | | 2 | Usage: unknown command or option, a malformed setup code, an unknown card, a missing confirmation. | | 3 | Not paired: run `libbui pair` first. | | 130 | Interrupted with `Ctrl-c`. | ## Examples ```sh # titles you can renew today, from the JSON output libbui loans --json | jq -r '.[] | select(.renewable) | .title' # save every downloadable loan into a folder of your choice libbui download --all --dir ~/Books/Library # is this ebook available right now at the library? libbui search "the dispossessed" --kind ebook --available ```