Concepts
Shelves
Updated 6 Oct 2026
On this page
For agents
Load this page when: you are setting up a project shelf or your agent ignores the books you expect
- Set the active shelf with
trove shelf use <slug>. A shelf is a preference, not a filter. - Share a shelf with the repo through
trove initand by committing.trove/shelf.json. - If
trove shelfreports an unrecognized subcommand, the CLI is old. Runtrove setup.
A shelf is a named group of books. When a project has an active shelf, your agent reads those books first and marks them with a star in the reading list.
Ask your agent
| Task | What to tell your agent |
|---|---|
| List shelves | "List my Trove shelves." |
| Create a shelf | "Create a Trove shelf called Platform." |
| Add books | "Add the Postgres book to my Platform shelf." |
| Remove books | "Remove the old style guide from my Platform shelf." |
| Make it active here | "Use the Platform shelf for this project." |
| Clear the active shelf | "Stop using a Trove shelf in this project." |
| Show the active shelf | "Which Trove shelf does this project use?" |
| Sync with the repo file | "Sync the Trove shelf file in this repo with my account." |
Active shelf for a project
Ask your agent to use a shelf from inside a project folder. Trove stores the pointer in ~/.trove/projects/<key>/active-shelf, never inside your repo. Another project can use a different shelf.
Share a shelf with your repo
Ask your agent: "Create a Trove shelf for this project." To start from a shelf you already have, ask: "Share my Platform shelf with this repo." Your agent writes ./.trove/shelf.json. Commit .trove/shelf.json, and teammates get the same shelf. If the file and your account do not match, ask your agent to sync them.
Hosts without a session hook (Cursor, GitHub Copilot, Gemini CLI, Grok) read .trove/shelf.json themselves.
Best practice
Make one shelf for each project, and commit .trove/shelf.json so every teammate reads the same books. Make a topic shelf for knowledge that many projects share. See Build a project shelf.
Soft preference, not a filter
Shelf books lead the reading list, but the librarian still scans your whole library and the marketplace. A better book outside the shelf can still appear. If you want a book to always be considered first, add it to the shelf.
Errors
| Message | Fix |
|---|---|
| unrecognized subcommand 'shelf' | Your CLI is old. Run trove setup. |
| The shelf you expect is not used | Ask your agent which shelf this project uses. Then ask it to use the correct one. |
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 shelves | trove shelf list |
| Create a shelf | trove shelf create "<name>" |
| Add books | trove shelf add <shelf> <ids> |
| Remove books | trove shelf remove <shelf> <ids> |
| Make it active here | trove shelf use <slug> |
| Clear the active shelf | trove shelf use --clear |
| Show the active shelf | trove shelf current |
| Write the repo file | trove init --from <shelf>, or trove init --name <name> for a new shelf |
| Sync with the repo file | trove shelf sync |
See the CLI reference for every flag.
Related
- Build a project shelf says how to build and grow a shelf.
- Library and books covers the books a shelf holds.
- How Trove works shows where shelves feed the librarian.