---
title: "trove items, writing"
description: "Use when you add a file, create or edit a markdown book, append to it, import a large file, roll back a version, or remove or re-import a book with the trove items commands."
url: https://docs.heytrove.ai/reference/cli/items-writing
updated: 2026-10-01
---

# trove items, writing

> Load this page when: you need to add, create, edit, append to, import, restore or remove a book from the terminal

## For agents

- 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](https://docs.heytrove.ai/reference/cli/items.md). Reader requests are on [trove items: gaps](https://docs.heytrove.ai/reference/cli/items-gaps.md).

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

```bash
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**

```bash
trove items add ./use-the-index-luke.pdf
```

**Output**

```terminal
✓ 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](https://docs.heytrove.ai/reference/plans-and-limits.md).

REST equivalent: [Upload API](https://docs.heytrove.ai/reference/api/upload.md).

## trove items create

Creates a markdown book.

**Usage**

```bash
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**

```bash
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](https://docs.heytrove.ai/reference/api/items.md#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**

```bash
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**

```terminal
✓ 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**

```bash
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**

```bash
trove items put cmabc123:4 --file page4.md --expect-version 7
```

**Errors**

| 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](https://docs.heytrove.ai/reference/api/items-write.md#replace-a-whole-book).

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

```bash
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](https://docs.heytrove.ai/reference/api/items-write.md#append-or-prepend-pages).

## trove items history

Lists the versions you can restore, newest first. Only the owner can list versions. The call counts as one read.

**Usage**

```bash
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](https://docs.heytrove.ai/reference/api/items-write.md#list-versions).

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

```bash
trove items restore ID --version N
```

**Output**

```terminal
✓ 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](https://docs.heytrove.ai/reference/api/items-write.md#restore-a-version).

## trove items remove

Deletes books you own. A deleted book cannot be recovered. Text output only.

**Usage**

```bash
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](https://docs.heytrove.ai/reference/cli/marketplace.md).

REST equivalent: [Items API](https://docs.heytrove.ai/reference/api/items.md#delete-items).

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

```bash
trove items reprocess ID
```

REST equivalent: [Items API](https://docs.heytrove.ai/reference/api/items.md#reprocess-a-book).

## trove items enrich

Sets metadata on a book. Pass at least one field. Text output only.

**Usage**

```bash
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**

```terminal
✓ Enriched: Use The Index, Luke (ID: cmabc123)
  Confidence: 90.0%
```

REST equivalent: [Items API](https://docs.heytrove.ai/reference/api/items.md#enrich-a-book).

## trove items flag

Marks a book as needing enrichment. Use it when the content looks incomplete or garbled. Text output only.

**Usage**

```bash
trove items flag ID
```

REST equivalent: [Items API](https://docs.heytrove.ai/reference/api/items.md#flag-a-book).