Reference
trove items, gaps
Updated 1 Oct 2026
On this page
For agents
Load this page when: you need to report a missing topic in a book, or manage the reader requests for books you wrote
- 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 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
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
trove items report-gap --item cmabc123 --intent "retry strategy for flaky jobs" --category devops --subcategory "retry backoff"Output
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.
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
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
trove items gaps cmabc123 --status openOutput
Reader requests
retry backoff [OPEN] · 3 readers
category: devops
sample: retry strategy for flaky jobsWith --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.
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
trove items resolve-gap ID --subcategory TEXTArguments 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
trove items resolve-gap cmabc123 --subcategory "retry backoff"Output
✓ Marked "retry backoff" covered — notified 3 reader(s).REST equivalent: Gaps API.
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
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
trove items restore-gap cmabc123 "retry backoff"Output
✓ Restored "retry backoff" to open — 3 request(s).Errors
| Message | Fix |
|---|---|
Provide gapIds or subcategory | Pass a sub-topic. |
REST equivalent: Gaps API.