---
title: "trove items, gaps"
description: "Use when a book you read is missing a topic and you report it to the author, or when you wrote a book and want to see, resolve or reopen reader requests with the trove items commands."
url: https://docs.heytrove.ai/reference/cli/items-gaps
updated: 2026-10-01
---

# trove items, gaps

> Load this page when: you need to report a missing topic in a book, or manage the reader requests for books you wrote

## For agents

- Report a missing sub-topic with trove items report-gap. State the subject, never the user's own words.
- Authors list requests with trove items gaps, then close one with trove items resolve-gap after extending the book.
- Mind the asymmetry. resolve-gap takes --subcategory, and restore-gap takes it as a positional argument.

A gap is a topic a reader looked for in a book and did not find. Readers and their agents report gaps. The author sees them as requests. See [Knowledge gaps](https://docs.heytrove.ai/concepts/knowledge-gaps.md) for the idea.

## Quick reference

| Command | Who runs it | What it does |
| --- | --- | --- |
| `trove items report-gap` | Reader | Report a missing topic in a book |
| `trove items gaps` | Author | Show requests for one book, or a summary of all your books |
| `trove items resolve-gap` | Author | Mark a topic as covered and notify readers |
| `trove items restore-gap` | Author | Move a declined request back to open |

## trove items report-gap

Sends a reader request to the author of a book you read. The call is fire and forget. A failure prints a warning and the command still exits cleanly, so a reader agent never blocks on it. Text output only.

**Usage**

```bash
trove items report-gap --item ID --intent TEXT --category TEXT --subcategory TEXT [--section TEXT]
```

**Arguments and flags**

| Flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `--item` | id | required | Book the gap is about. |
| `--intent` | text | required | The topic the reader was after. Leave out personal details. |
| `--category` | text | required | Broad category, such as `programming`. |
| `--subcategory` | text | required | The missing sub-topic, such as `retry backoff`. |
| `--section` | text | none | Chapter or section the gap relates to. |

**Example**

```bash
trove items report-gap --item cmabc123 --intent "retry strategy for flaky jobs" --category devops --subcategory "retry backoff"
```

**Output**

```terminal
Reader request submitted.
```

The wording stays neutral on purpose. A 2xx reply does not prove a row was written, because the server removes duplicates.

**Errors**

| Message | Fix |
| --- | --- |
| `warning: reader request skipped ({reason})` | You are not signed in. Run `trove auth login`. |
| `warning: reader request failed ({reason}) — continuing` | Nothing to fix. The report is optional. |

REST equivalent: [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md#report-a-missing-topic-in-a-book).

## trove items gaps

Shows reader requests for books you wrote. With an id, it shows one book. Without an id, it summarizes all your books.

**Usage**

```bash
trove items gaps [ID] [--status open|fulfilled|dismissed] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `ID` | id | all your books | Book to show. |
| `--status` | open, fulfilled or dismissed | open | Which requests to show. Needs an id. |

**Example**

```bash
trove items gaps cmabc123 --status open
```

**Output**

```terminal
Reader requests

  retry backoff [OPEN] · 3 readers
    category: devops
    sample: retry strategy for flaky jobs
```

With `--json` and an id, the output is an array of groups. Each group has `subcategory`, `category`, `reporterCount`, `sampleIntent`, `status`, `latestAt` and `gapIds`. Without an id, it is an array of books with `itemId`, `itemTitle`, `openCount` and `topSubcategories`.

**Errors**

| Message | Fix |
| --- | --- |
| `Item not found` | Only the owner can list requests. Check the id. |
| `No open reader requests for this book.` | Nothing is waiting. Try `--status fulfilled`. |

REST equivalent: [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md#list-requests-for-a-book).

## trove items resolve-gap

Marks a sub-topic as covered after you extended the book. Every reader who asked is notified. Text output only.

**Usage**

```bash
trove items resolve-gap ID --subcategory TEXT
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `ID` | id | required | Book you wrote. |
| `--subcategory` | text | required | Sub-topic to mark as covered. Passed as a flag. |

**Example**

```bash
trove items resolve-gap cmabc123 --subcategory "retry backoff"
```

**Output**

```terminal
✓ Marked "retry backoff" covered — notified 3 reader(s).
```

REST equivalent: [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md#mark-requests-as-covered).

## trove items restore-gap

Moves a declined request back to open. No one is notified. Here the sub-topic is a positional argument, not a flag. This differs from `resolve-gap`.

**Usage**

```bash
trove items restore-gap ID SUBCATEGORY [--json]
```

**Arguments and flags**

| Argument | Value | Default | Meaning |
| --- | --- | --- | --- |
| `ID` | id | required | Book you wrote. |
| `SUBCATEGORY` | text | required | Sub-topic to reopen. |

**Example**

```bash
trove items restore-gap cmabc123 "retry backoff"
```

**Output**

```terminal
✓ Restored "retry backoff" to open — 3 request(s).
```

**Errors**

| Message | Fix |
| --- | --- |
| `Provide gapIds or subcategory` | Pass a sub-topic. |

REST equivalent: [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md#reopen-declined-requests).