---
title: "trove marketplace"
description: "Use when you browse the public marketplace, add a listed book to your library, or remove one again with the trove marketplace commands."
url: https://docs.heytrove.ai/reference/cli/marketplace
updated: 2026-10-01
---

# trove marketplace

> Load this page when: you need to find, add or remove a marketplace book from the terminal

## For agents

- Browse with trove marketplace browse. It needs no sign-in.
- Add a book only when the user wants it, because every added book uses a library slot.
- Pass --json to subscribe to get a result envelope with a code you can branch on.

The marketplace is the public shelf of books other people published. Adding one is free and takes no payment. See [Marketplace](https://docs.heytrove.ai/concepts/marketplace.md) for the idea.

## Quick reference

| Command | What it does |
| --- | --- |
| `trove marketplace browse` | List public books |
| `trove marketplace subscribe` | Add a listed book to your library |
| `trove marketplace unsubscribe` | Remove it again |

## trove marketplace browse

Lists public listings. It needs no sign-in.

**Usage**

```bash
trove marketplace browse [--search TEXT] [--limit N] [--sort ORDER] [--tag SLUG] [--json]
```

**Arguments and flags**

| Flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `--search`, `-s` | text | none | Search query. |
| `--limit`, `-l` | integer | server default | Maximum results. |
| `--sort` | newest, popular or az | newest | Sort order. |
| `--tag`, `-t` | tag slug | none | Show one tag only. |

**Example**

```bash
trove marketplace browse --search postgres --sort popular --limit 5
```

**Output**

```terminal
┌──────────┬─────────────────────┬───────────────┬──────────┬─────────────┬───────┐
│ ID       │ Title               │ Author        │ Tags     │ Subscribers │ Pages │
├──────────┼─────────────────────┼───────────────┼──────────┼─────────────┼───────┤
│ cmlst123 │ Use The Index, Luke │ Markus Winand │ postgres │ 120         │ 42    │
└──────────┴─────────────────────┴───────────────┴──────────┴─────────────┴───────┘
```

With `--json` the output has `listings`, `total`, `page` and `totalPages`. Each listing has `id`, `slug`, `category`, `proOnly`, `tags`, `subscriberCount`, `createdAt`, `item` and `seller`.

The ID in this table is the listing id. Pass it to `subscribe`.

REST equivalent: [Marketplace API](https://docs.heytrove.ai/reference/api/marketplace.md#browse-listings).

## trove marketplace subscribe

Adds a listed book to your library. It uses one library slot. A Pro-only listing can be added on any plan, but it returns a short preview until you upgrade.

**Usage**

```bash
trove marketplace subscribe LISTING_ID [--domain TEXT] [--title TEXT] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `LISTING_ID` | listing id | required | Listing from `browse`. |
| `--domain` | text | none | Used by the librarian to log the result in the project ledger. Skip it when you run the command yourself. |
| `--title` | text | none | Book title for that ledger row. Needs `--domain`. |

**Example**

```bash
trove marketplace subscribe cmlst123 --json
```

**Output**

```terminal
✓ Subscribed to listing cmlst123
  Item added to library: cmabc123
```

```json
{
  "success": true,
  "itemId": "cmabc123",
  "recorded": false
}
```

When the call fails with `--json`, the output is still JSON: `success` is false, with `code`, `status`, `error`, `itemId` and `recorded`. `code` is one of `PLAN_LIMIT_EXCEEDED`, `CONFLICT` or `TRANSIENT_CONFLICT`, or `null`.

**Errors**

| Message | Fix |
| --- | --- |
| `Your library is full. Upgrade to add more items.` | Remove a book, or upgrade. See [Plans and limits](https://docs.heytrove.ai/reference/plans-and-limits.md). |
| `Already subscribed to this listing` | Nothing to do. The book is in your library. |
| `Cannot subscribe to your own listing` | You already own this book. |
| `Listing not found` | Check the listing id with `browse`. |

REST equivalent: [Marketplace API](https://docs.heytrove.ai/reference/api/marketplace.md#add-a-listing-to-your-library).

## trove marketplace unsubscribe

Removes a marketplace book from your library and frees one slot. The seller's book is not affected. You can add it again while it is listed.

**Usage**

```bash
trove marketplace unsubscribe LISTING_ID [--json]
```

**Output**

```terminal
✓ Unsubscribed from listing cmlst123
```

**Errors**

| Message | Fix |
| --- | --- |
| `No subscription found for this listing` | You have not added this listing. |

REST equivalent: [Marketplace API](https://docs.heytrove.ai/reference/api/marketplace.md#remove-a-listing-from-your-library).