---
title: "trove shelf"
description: "Use when you group books on shelves, pin a project to a shelf, or share a shelf manifest with your team using trove shelf and trove init."
url: https://docs.heytrove.ai/reference/cli/shelf
updated: 2026-10-01
---

# trove shelf

> Load this page when: you need to create or change a shelf, set the active shelf, or run trove init and trove shelf sync

## For agents

- Pass --confirm to trove shelf delete when the shelf holds books.
- Use trove init to write ./.trove/shelf.json, then trove shelf sync to reconcile it with the cloud shelf.
- Every shelf argument takes a slug, an id or a name that ignores case.

A shelf is a named group of books. The librarian ranks books on the active shelf higher. See [Shelves](https://docs.heytrove.ai/concepts/shelves.md) for the idea.

## Quick reference

| Command | What it does |
| --- | --- |
| `trove shelf list` | List your shelves |
| `trove shelf show` | Show a shelf and its books |
| `trove shelf create` | Create a shelf |
| `trove shelf rename` | Rename a shelf |
| `trove shelf delete` | Delete a shelf. The books stay in your library |
| `trove shelf add` | Add books to a shelf |
| `trove shelf remove` | Remove books from a shelf |
| `trove shelf use` | Set the active shelf for this project |
| `trove shelf current` | Show the active shelf |
| `trove shelf sync` | Reconcile `./.trove/shelf.json` with the cloud shelf |
| `trove init` | Create the shelf manifest |

## trove shelf list

Lists your shelves. A star marks the active shelf for the current directory.

**Usage**

```bash
trove shelf list [--json]
```

**Output**

```terminal
┌───┬──────────┬──────────┬───────┬─────────┬─────┐
│   │ Name     │ Slug     │ Items │ Color   │ Pos │
├───┼──────────┼──────────┼───────┼─────────┼─────┤
│ * │ Backend  │ backend  │ 4     │ #5B7CFA │ 0   │
└───┴──────────┴──────────┴───────┴─────────┴─────┘
```

With `--json` the output is `{ "shelves": [...] }`. Each shelf has `id`, `name`, `slug`, `color`, `position` and `itemCount`.

REST equivalent: [Shelves API](https://docs.heytrove.ai/reference/api/shelves.md#list-shelves).

## trove shelf show

Shows one shelf and its books, in the same table as `trove items list`.

**Usage**

```bash
trove shelf show TARGET [--json]
```

**Arguments and flags**

| Argument | Value | Default | Meaning |
| --- | --- | --- | --- |
| `TARGET` | slug, id or name | required | Shelf to show. |

With `--json` the output has `shelf`, `items`, `enrichmentQueue` and `pickUrl`.

**Errors**

| Message | Fix |
| --- | --- |
| `Shelf '{name}' not found. Available: {list}` | Use a name from the list. |

## trove shelf create

Creates a shelf. The slug comes from the name.

**Usage**

```bash
trove shelf create NAME [--color HEX] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `NAME` | text, 1 to 50 characters | required | Display name. |
| `--color` | `#RRGGBB` | none | Six-digit hex color. |

**Example**

```bash
trove shelf create Backend --color "#5B7CFA"
```

**Output**

```terminal
✓ Created shelf 'Backend' (slug: backend)
```

**Errors**

| Message | Fix |
| --- | --- |
| `A shelf with this name already exists` | Pick another name. |
| `Shelf limit reached ({n}). Delete an unused shelf to make room.` | Delete a shelf you no longer use. |

REST equivalent: [Shelves API](https://docs.heytrove.ai/reference/api/shelves.md#create-a-shelf).

## trove shelf rename

Renames a shelf. The slug changes with the name.

**Usage**

```bash
trove shelf rename TARGET NEW_NAME [--json]
```

**Example**

```bash
trove shelf rename backend "Backend services"
```

**Output**

```terminal
✓ Renamed 'Backend' → 'Backend services' (slug: backend-services)
```

## trove shelf delete

Deletes a shelf. Books on it stay in your library.

**Usage**

```bash
trove shelf delete TARGET [--confirm] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `TARGET` | slug, id or name | required | Shelf to delete. |
| `--confirm` | none | off | Required when the shelf is not empty. Agents must pass it on purpose. |

**Errors**

| Message | Fix |
| --- | --- |
| `Shelf '{name}' has {n} item(s). Re-run with --confirm to delete.` | Re-run with `--confirm`. |

REST equivalent: [Shelves API](https://docs.heytrove.ai/reference/api/shelves.md#delete-a-shelf).

## trove shelf add

Adds one or more books to a shelf. Adding a book that is already there changes nothing.

**Usage**

```bash
trove shelf add SHELF ITEMS... [--json]
```

**Arguments and flags**

| Argument | Value | Default | Meaning |
| --- | --- | --- | --- |
| `SHELF` | slug, id or name | required | Target shelf. |
| `ITEMS` | one or more ids | required | Books to add. |

**Example**

```bash
trove shelf add backend cmabc123 cmdef456
```

**Output**

```terminal
✓ Added 2 items to 'Backend'.
```

With `--json` the output has `added` and, for ids you cannot access, `notFound`.

**Errors**

| Message | Fix |
| --- | --- |
| `Provide at least one item id to add.` | Pass an id. |

REST equivalent: [Shelves API](https://docs.heytrove.ai/reference/api/shelves.md#add-books-to-a-shelf).

## trove shelf remove

Removes books from a shelf. The books stay in your library.

**Usage**

```bash
trove shelf remove SHELF ITEMS... [--json]
```

**Output**

```terminal
✓ Removed 1 item from 'Backend'.
```

With `--json` the output is `{ "removed": 1 }`.

REST equivalent: [Shelves API](https://docs.heytrove.ai/reference/api/shelves.md#remove-books-from-a-shelf).

## trove shelf use

Sets the active shelf for this project. The pointer lives in `~/.trove/projects/<project>/active-shelf`, never in the repository. A `./.trove/shelf.json` file takes precedence over it.

**Usage**

```bash
trove shelf use [TARGET] [--clear] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `TARGET` | slug, id or name | none | Shelf to use. Omit it with `--clear`. |
| `--clear` | none | off | Clear the active shelf. |

**Output**

```terminal
✓ Now using shelf 'Backend' (4 books). The librarian will give books in this shelf a relevance boost.
```

## trove shelf current

Shows the active shelf for this project.

**Usage**

```bash
trove shelf current [--json]
```

With `--json` the output has the same shape as `trove shelf show`. It prints nothing when no shelf is set.

## trove shelf sync

Reconciles `./.trove/shelf.json` with its cloud shelf. By default the file wins: the cloud shelf is changed to match it, then titles and authors in the file are refreshed.

**Usage**

```bash
trove shelf sync [--from-cloud] [--dry-run] [--yes] [--json]
```

**Arguments and flags**

| Flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `--from-cloud` | none | off | Reverse the direction. Rewrite the file's books from the cloud shelf. The `why` and `topics` of kept books stay. |
| `--dry-run` | none | off | Show the changes and apply nothing. |
| `--yes` | none | off | Apply removals without a prompt. Needed when the file lists no books but the cloud shelf is not empty. |

**Example**

```bash
trove shelf sync --dry-run
```

**Output**

```terminal
Dry run — shelf 'Backend' would change:
  + cmdef456
  - cmold789
```

**Errors**

| Message | Fix |
| --- | --- |
| ``No ./.trove/shelf.json in this directory. Run `trove init` to create one.`` | Run `trove init`. |
| `Sync would remove {n} book(s) from shelf '{name}' ({ids}). Re-run with --yes to confirm or --dry-run to preview.` | Check the list, then re-run with `--yes`. |
| `Shelf '{slug}' declared in ./.trove/shelf.json was not found in your account` | The shelf was deleted. Run `trove init --name` for a new one. |

## trove init

Creates `./.trove/shelf.json`. Commit the file so your team and agents share the same shelf. Use exactly one of `--from` or `--name`.

**Usage**

```bash
trove init [--from SHELF | --name NAME] [--json]
```

**Arguments and flags**

| Flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `--from` | slug, id or name | none | Seed the file from an existing cloud shelf. Conflicts with `--name`. |
| `--name` | text | none | Create a new empty cloud shelf and link it. Conflicts with `--from`. |

**Example**

```bash
trove init --name "Billing service"
```

**Output**

```terminal
✓ Created shelf 'Billing service' (slug: billing-service)
✓ Wrote ./.trove/shelf.json (shelf 'billing-service', 0 books)
  Commit this file so your team and agents share the same shelf contract.
```

**Errors**

| Message | Fix |
| --- | --- |
| ``./.trove/shelf.json already exists. Edit it directly, or run `trove shelf sync` to reconcile it with the cloud.`` | Edit the file, or sync. |
| `Nothing to initialize from — no active shelf in this directory.` | Pass `--from` or `--name`. |