---
title: "Shelves"
description: "Use when you want your agent to read certain books first for one project, or to share that choice with your repo and teammates."
url: https://docs.heytrove.ai/concepts/shelves
updated: 2026-10-06
---

# Shelves

> Load this page when: you are setting up a project shelf or your agent ignores the books you expect

## For agents

- 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 init` and by committing `.trove/shelf.json`.
- If `trove shelf` reports an unrecognized subcommand, the CLI is old. Run `trove setup`.

A shelf is a named group of [books](https://docs.heytrove.ai/concepts/library-and-books.md). 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](https://docs.heytrove.ai/best-practices/project-shelf.md).

## Soft preference, not a filter

Shelf books lead the reading list, but the [librarian](https://docs.heytrove.ai/subagents/librarian.md) still scans your whole library and the [marketplace](https://docs.heytrove.ai/concepts/marketplace.md). 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](https://docs.heytrove.ai/reference/cli.md) for every flag.

## Related

- [Build a project shelf](https://docs.heytrove.ai/best-practices/project-shelf.md) says how to build and grow a shelf.
- [Library and books](https://docs.heytrove.ai/concepts/library-and-books.md) covers the books a shelf holds.
- [How Trove works](https://docs.heytrove.ai/how-trove-works.md) shows where shelves feed the librarian.