Reference

trove shelf

Updated 1 Oct 2026

View as Markdown Open in Claude (opens in a new tab)Open in ChatGPT (opens in a new tab)

On this page

Quick reference
trove shelf list
trove shelf show
trove shelf create
trove shelf rename
trove shelf delete
trove shelf add
trove shelf remove
trove shelf use
trove shelf current
trove shelf sync
trove init

For agents

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

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 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

┌───┬──────────┬──────────┬───────┬─────────┬─────┐
│   │ 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.

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

✓ 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.

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

✓ 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.

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

✓ 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.

trove shelf remove

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

Usage

bash

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

Output

✓ Removed 1 item from 'Backend'.

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

REST equivalent: Shelves API.

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

✓ 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

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

✓ 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`.

trove shelf

For agents

Quick reference#

trove shelf list#

trove shelf show#

trove shelf create#

trove shelf rename#

trove shelf delete#

trove shelf add#

trove shelf remove#

trove shelf use#

trove shelf current#

trove shelf sync#

trove init#

Quick reference

trove shelf list

trove shelf show

trove shelf create

trove shelf rename

trove shelf delete

trove shelf add

trove shelf remove

trove shelf use

trove shelf current

trove shelf sync

trove init