Reference
trove items, writing
Updated 1 Oct 2026
On this page
For agents
Load this page when: you need to add, create, edit, append to, import, restore or remove a book from the terminal
- Pass --expect-version to put whenever several agents can write to the same book.
- Use append when you only add content, because it never conflicts.
- Run trove items history before a restore, because restoring version N brings back the text from version N-1.
These commands change your library. Reading commands are on trove items: read. Reader requests are on trove items: gaps.
Quick reference
| Command | What it does |
|---|---|
trove items add | Upload a PDF, EPUB or Markdown file |
trove items create | Create a markdown book from text |
trove items import | Import a big markdown file as one book |
trove items put | Replace a whole book, or one page |
trove items append | Add content to the end or the start |
trove items history | List restorable versions |
trove items restore | Go back to an earlier version |
trove items remove | Delete books |
trove items reprocess | Rebuild a book from its original file |
trove items enrich | Set title, author, description and table of contents |
trove items flag | Mark a book as needing enrichment |
trove items add
Uploads a file and returns when the import job is queued. Run trove items status --wait to block until it is done. Text output only.
Usage
trove items add FILE [--replace] [--force]Arguments and flags
| Argument or flag | Value | Default | Meaning |
|---|---|---|---|
FILE | PDF, EPUB or Markdown path | required | File to upload. |
--replace | none | off | If a similar book exists, replace it. The old copy is removed. |
--force, -f | none | off | Skip the duplicate check and upload as a new copy. |
Example
trove items add ./use-the-index-luke.pdfOutput
✓ Added: Use The Index, Luke (ID: cmabc123)Add errors: Unsupported file type, Your library is full. Upgrade to add more items. and File exceeds {n}MB limit. See Plans and limits.
REST equivalent: Upload API.
trove items create
Creates a markdown book.
Usage
trove items create TITLE [--description TEXT] [--content TEXT] [--json]Arguments and flags
| Argument or flag | Value | Default | Meaning |
|---|---|---|---|
TITLE | text | required | Book title. |
--description, -d | text | none | Short description. |
--content, -c | markdown | empty | Initial content. Top-level # headings split it into pages. |
Example
trove items create "Team runbook" -c "# Deploys"With --json the output has id, title, description, sourceType, status, pageCount, createdAt and updatedAt.
REST equivalent: Create a markdown book.
trove items import
Imports a whole markdown file as a new book. It cuts the upload only at # heading boundaries. Text output only.
Usage
trove items import FILE [--title TITLE]Arguments and flags
| Argument or flag | Value | Default | Meaning |
|---|---|---|---|
FILE | markdown path | required | File to import. |
--title | text | first # heading, else the file name | Book title. |
A book is capped at 30 MB in total. Split a larger file into several books at parts or volumes, and import each one. If the file is over the cap, the CLI says {file} is {n} MB — a single book is capped at a fixed 30 MB….
Output
✓ Imported: Engineering handbook (ID: cmhand789)trove items put
Replaces the content of a whole book, or of one page. Everything not in the new content is deleted. Text output only.
Usage
trove items put ID[:PAGE] [--file FILE] [--expect-version N]Arguments and flags
| Argument or flag | Value | Default | Meaning |
|---|---|---|---|
ID[:PAGE] | id, optionally with a page | required | Whole book, or just that page. |
--file, -f | path | stdin | Read the content from a file. |
--expect-version | integer | none | The version you read. The write is refused if anyone wrote since. |
A whole-document write is capped at 1 MB. A page write sends only that page, so it works on bigger books. One page is exactly one top-level # section. Page 1 may be a preamble with no heading.
Example
trove items put cmabc123:4 --file page4.md --expect-version 7Errors
| Message | Fix |
|---|---|
This book changed since you read it - you based this write on version {a} and it is now version {b}. Your write was NOT applied and nothing was lost. | Read the book again, redo your edit, and write with --expect-version {b}. |
content would split into {n} pages — pages are split on top-level "# " headings and this operation replaces exactly one page. | Keep one # heading. Demote the others to ##. |
This item is read-only for your account — … | Ask the owner for write access. |
REST equivalent: Writing API.
trove items append
Adds content to the end of a book, or to the start. Only the new text travels, and it never conflicts with another writer. Start it with a # heading so it becomes its own page. Text output only.
Usage
trove items append ID [--file FILE] [--prepend]Arguments and flags
| Argument or flag | Value | Default | Meaning |
|---|---|---|---|
ID | id | required | Book to extend. |
--file, -f | path | stdin | Read the content from a file. |
--prepend | none | off | Insert at the start. |
REST equivalent: Writing API.
trove items history
Lists the versions you can restore, newest first. Only the owner can list versions. The call counts as one read.
Usage
trove items history ID [--json]With --json the output has id, title, currentVersion, versions and note. Each version has version, savedAt, bytes and describes.
REST equivalent: Writing API.
trove items restore
Restores an earlier version. The current text is saved first, so a restore can itself be undone. Restoring version N brings back the text the book held at version N-1. Text output only.
Usage
trove items restore ID --version NOutput
✓ Restored version 8 of Use The Index, Luke (ID: cmabc123)Errors
| Message | Fix |
|---|---|
No snapshot at version {n}. Available versions: {list} | Pick a version from the list. |
REST equivalent: Writing API.
trove items remove
Deletes books you own. A deleted book cannot be recovered. Text output only.
Usage
trove items remove IDS [--yes]Arguments and flags
| Argument or flag | Value | Default | Meaning |
|---|---|---|---|
IDS | comma-separated ids | required | Books to delete. |
--yes, -y | none | off | Skip the confirmation prompt. |
Ids that are not your own books print Not found. Remove a marketplace book with trove marketplace.
REST equivalent: Items API.
trove items reprocess
Rebuilds a book from the file it was uploaded from. Use it when trove items list shows health partial or most pages are blank. The old pages stay readable until the new ones are ready. It does not help when the file has no readable text. Text output only.
Usage
trove items reprocess IDREST equivalent: Items API.
trove items enrich
Sets metadata on a book. Pass at least one field. Text output only.
Usage
trove items enrich ID [--title T] [--author A] [--description D] [--confidence N] [--toc JSON] [--add-prompt JSON] [--sample-question Q]Arguments and flags
| Flag | Value | Default | Meaning |
|---|---|---|---|
--title, --author, --description | text | unchanged | New value. |
--confidence | 0.0 to 1.0 | none | Confidence in the metadata. Below 80% the book stays flagged. |
--toc | JSON array | unchanged | Entries like [{"title":"Chapter 1","page":1,"level":1}]. |
--add-prompt | JSON object | none | {"prompt":"...","context":"...","multiBook":false}. prompt is required. |
--sample-question | text | none | A sample question for this book. |
Output
✓ Enriched: Use The Index, Luke (ID: cmabc123)
Confidence: 90.0%REST equivalent: Items API.
trove items flag
Marks a book as needing enrichment. Use it when the content looks incomplete or garbled. Text output only.
Usage
trove items flag IDREST equivalent: Items API.