--- title: "Library and books" description: "Use when you need to know what a book is in Trove, how to add, read, edit or repair one, or why a read or import failed." url: https://docs.heytrove.ai/concepts/library-and-books updated: 2026-10-06 --- # Library and books > Load this page when: you are adding, reading, editing or fixing a book, or a read command returned an error ## For agents - Read in pieces. Run `trove items list`, then `trove items toc `, then `trove items read ":7-9"`. - Edit Markdown books with `trove items get`, then `trove items put --expect-version ` so concurrent edits do not collide. - Never reprocess or edit a book that belongs to someone else. Your library is every book your agent can read. A book is one document that Trove has split into pages, so agents can read a range instead of the whole file. ## Ask your agent | Task | What to tell your agent | | --- | --- | | List books | "List the books in my Trove library." | | Show the table of contents | "Show the table of contents of the Postgres book in my Trove library." | | Read a page range | "Read pages 7 to 9 of the Postgres book in my Trove library." | | Add a file | "Add ./book.pdf to my Trove library." | | Wait for processing | "Tell me when the new book is ready in my Trove library." | | Remove books | "Remove the old style guide from my Trove library." | ## What counts as a book PDF, EPUB and Markdown files all become books. So do [marketplace](https://docs.heytrove.ai/concepts/marketplace.md) subscriptions and books that a [team](https://docs.heytrove.ai/concepts/teams.md) shares with you. Markdown books are editable by agents, and the other formats are read-only. ## Reading a book in pieces Your agent first reads the table of contents, which lists chapters with page numbers. Then it reads only the range it needs. You can name the pages yourself: ```text Read pages 7 to 9 of the Postgres book in my Trove library. ``` Ranges save reads and keep your agent's context small. Reading a whole book is for short books. ## Editing a markdown book Ask your agent: "Add a section on retries to our API guide in my Trove library." Your agent fetches the current text and version, makes the change and saves it. The save fails if someone else saved first, so two edits do not collide. Your agent then reads the new version and does the edit again. Every save is kept. Ask your agent: "Show the versions of our API guide." To go back, ask: "Restore the API guide to the version from yesterday." ## Fixing a bad import If a PDF came out garbled or incomplete, ask your agent: "Reprocess the Postgres book in my Trove library and tell me when it is ready." ## Errors | Message | Fix | | --- | --- | | Items not found | The id belongs to a marketplace listing you have not subscribed to. Ask your agent to subscribe to that listing. | | A book is locked on the Personal plan | Upgrade at [billing](https://heytrove.ai/billing), or choose which books stay usable. | | Reading stops at the monthly read limit | Wait for the reset, or upgrade at [billing](https://heytrove.ai/billing). See [plans and limits](https://docs.heytrove.ai/reference/plans-and-limits.md). | ## Best practice Add your own documents first, because they beat famous books. After you add a book, wait until it is ready. Then ask your agent to read its table of contents and open a few pages. If the title or contents look weak, ask your agent: "Enrich the metadata of this book in my Trove library." A new library should start by turning your existing agent skills into books. See [Set up your library](https://docs.heytrove.ai/usage/set-up-your-library.md). ## Direct CLI Your agent runs these through the `trove` command. You can run them yourself in a terminal, but asking your agent is the recommended way: it picks the right flags, waits for processing and checks the result. | Task | Command | | --- | --- | | List books | `trove items list` | | Show the table of contents | `trove items toc ` | | Read a page range | `trove items read ":7-9"`, `trove items read --pages 1-3,7`, `trove items read ":1-5,:all"` | | Add a file | `trove items add ` | | Wait for processing | `trove items status --wait` | | Remove books | `trove items remove ` | | Edit a Markdown book | `trove items get `, then `trove items put --expect-version `; `trove items append` adds text at the end | | Versions | `trove items history `, `trove items restore --version ` | | Reprocess | `trove items reprocess ` | | Enrich metadata | `trove items enrich ` | | Subscribe to a listing | `trove marketplace subscribe ` | See the [CLI reference](https://docs.heytrove.ai/reference/cli.md) for every flag. ## Related - [What goes in the library](https://docs.heytrove.ai/best-practices/what-goes-in-the-library.md) says what to add and what to keep out. - [Set up your library](https://docs.heytrove.ai/usage/set-up-your-library.md) turns your agent skills into books. - [Write books agents can read](https://docs.heytrove.ai/best-practices/write-books-agents-can-read.md) covers chapter structure and page-level edits. - [Marketplace](https://docs.heytrove.ai/concepts/marketplace.md) adds books from other authors. - [Shelves](https://docs.heytrove.ai/concepts/shelves.md) group books by project. - [Plans and limits](https://docs.heytrove.ai/reference/plans-and-limits.md) lists every cap.