Concepts
Library and books
Updated 6 Oct 2026
On this page
For agents
Load this page when: you are adding, reading, editing or fixing a book, or a read command returned an error
- Read in pieces. Run
trove items list, thentrove items toc <ids>, thentrove items read "<id>:7-9". - Edit Markdown books with
trove items get, thentrove items put <id> --expect-version <n>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 subscriptions and books that a team 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:
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, or choose which books stay usable. |
| Reading stops at the monthly read limit | Wait for the reset, or upgrade at billing. See plans and limits. |
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.
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 <ids> |
| Read a page range | trove items read "<id>:7-9", trove items read <id> --pages 1-3,7, trove items read "<id1>:1-5,<id2>:all" |
| Add a file | trove items add <file> |
| Wait for processing | trove items status <id> --wait |
| Remove books | trove items remove <ids> |
| Edit a Markdown book | trove items get <id>, then trove items put <id> --expect-version <n>; trove items append adds text at the end |
| Versions | trove items history <id>, trove items restore <id> --version <n> |
| Reprocess | trove items reprocess <id> |
| Enrich metadata | trove items enrich <id> |
| Subscribe to a listing | trove marketplace subscribe <listing-id> |
See the CLI reference for every flag.
Related
- What goes in the library says what to add and what to keep out.
- Set up your library turns your agent skills into books.
- Write books agents can read covers chapter structure and page-level edits.
- Marketplace adds books from other authors.
- Shelves group books by project.
- Plans and limits lists every cap.