---
title: "trove items, reading"
description: "Use when you list your books, read a table of contents, read pages, wait for an import to finish or export a whole book with the trove items commands."
url: https://docs.heytrove.ai/reference/cli/items
updated: 2026-10-01
---

# trove items, reading

> Load this page when: you need to find books, read a table of contents or read pages from the terminal

## For agents

- List books, read the table of contents, then read only the pages you need.
- Pass --pages once for every id, or use the inline form with one range per id.
- Use trove items status --wait to block until an import is READY or FAILED.

These commands find books and read their text. Writing commands are on [trove items: write](https://docs.heytrove.ai/reference/cli/items-writing.md). Each book you open counts as one read.

## Quick reference

| Command | What it does |
| --- | --- |
| `trove items list` | List the books you can access |
| `trove items toc` | Show chapters and page ranges |
| `trove items read` | Read pages from one or more books |
| `trove items status` | Show import status, and optionally wait |
| `trove items get` | Print a whole book, or one page, to stdout |

## trove items list

Lists every book you can access. A locked book stays in the list with a `locked` marker.

**Usage**

```bash
trove items list [--shelf SHELF] [--json]
```

**Arguments and flags**

| Flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `--shelf` | slug, id or name | all books | Show only books on that shelf. The name match ignores case. |

**Example**

```bash
trove items list --shelf backend --json
```

**Output**

```terminal
┌──────────┬─────────────────────┬───────┬────────┬────────┬────────┐
│ ID       │ Title               │ Pages │ Status │ Health │ Enrich │
├──────────┼─────────────────────┼───────┼────────┼────────┼────────┤
│ cmabc123 │ Use The Index, Luke │ 42    │ READY  │ ok     │ ✓      │
└──────────┴─────────────────────┴───────┴────────┴────────┴────────┘
```

With `--json` the CLI prints the server response: `items`, `enrichmentQueue` and, when a book is locked, `pickUrl`. Each item has `id`, `title`, `author`, `pageCount`, `status`, `health`, `locked` and `shelves`.

**Errors**

| Message | Fix |
| --- | --- |
| `Shelf '{name}' not found. Available: {list}` | Use a shelf slug, id or name from the list. |
| `Not authenticated. Run 'trove auth login' first.` | Run `trove auth login`. |

REST equivalent: [List items](https://docs.heytrove.ai/reference/api/items.md#list-items).

## trove items toc

Shows the table of contents of one or more books, with page ranges.

**Usage**

```bash
trove items toc IDS [--json]
```

**Arguments and flags**

| Argument | Value | Default | Meaning |
| --- | --- | --- | --- |
| `IDS` | comma-separated ids | required | Books to show. |

**Example**

```bash
trove items toc cmabc123
```

**Output**

```terminal
============================================================ Use The Index, Luke
ID: cmabc123 | 42 pages
================================================================================
Anatomy of an Index (p. 1–9)
  The Leaf Nodes (p. 2–4)
Where Clauses (p. 10–25)
```

With `--json` the output has `items` and, for ids that were not found, `not_found`. Each item has `id`, `title`, `pageCount`, `toc` and `tocTree`.

**Errors**

| Message | Fix |
| --- | --- |
| `No item IDs provided` | Pass at least one id. |
| `No table of contents available.` | The book has no table of contents. Read by page range instead. |

REST equivalent: [Reading API](https://docs.heytrove.ai/reference/api/items-read.md#get-tables-of-contents).

## trove items read

Reads pages. You must say which pages: pass `--pages`, or put a range after each id.

**Usage**

```bash
trove items read IDS [--pages RANGE] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `IDS` | comma-separated ids | required | Books to read. Each id may carry an inline range, such as `id:1-5`. |
| `--pages` | `7-9`, `1,3,5`, `1-3,7` or `all` | none | Pages for every id. This is the only form that takes a comma list. |

The inline form takes `all` or ONE range per id: `"id1:1-5,id2:all"`. If you give both forms for one id, they must agree.

**Example**

```bash
trove items read "cmabc123:10-12" --no-session
```

**Output**

```terminal
────────────────────────────────────────────────────────────
Use The Index, Luke
ID: cmabc123 | 42 pages
────────────────────────────────────────────────────────────

── Page 10 ──

# Where Clauses
…
```

With `--json` the output has `items`, each with `pages` of `pageNum` and `content`. It also carries `truncatedItemIds` and `truncatedMessage` when a response hit its size budget. A truncated book is not empty.

**Errors**

| Message | Fix |
| --- | --- |
| `Missing page range for: {ids}` | Add `--pages` or an inline range. Use `all` for every page. |
| `Invalid page range '{range}'.` | Use `all`, `1-5`, `1,3,5` or `1-3,7,10`. Pages start at 1 and `N-M` needs M of N or more. |
| `Conflicting page ranges for '{id}': inline ':{range}' vs --pages '{pages}'. Use one form or the other.` | Remove one of the two. |
| `Trove: your agent has used all {limit} reads for {month}. Reads reset on {date}. Pro has unlimited reads: {host}/billing` | Stop and tell the user. Do not retry. |
| `This book is locked on the Personal plan. …` | Tell the user. Reads of that book are refused until they upgrade or pick it as a usable book. |

REST equivalent: [Reading API](https://docs.heytrove.ai/reference/api/items-read.md#read-pages-in-a-batch).

## trove items status

Shows whether imports have finished. Importing is asynchronous: `trove items add` returns when the job is queued.

**Usage**

```bash
trove items status IDS [--wait] [--timeout SECONDS] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `IDS` | comma-separated ids | required | Books to check. |
| `--wait` | none | off | Block until every book is READY or FAILED. |
| `--timeout` | seconds | 300 | Give up after this long. Needs `--wait`. |

The command exits non-zero when a book FAILED or the wait timed out. Processing continues on the server, so run it again to keep waiting.

**Example**

```bash
trove items status cmabc123 --wait --timeout 600
```

**Output**

```terminal
┌──────────┬──────────────────────────┬────────┬───────┬────────┐
│ ID       │ TITLE                    │ STATUS │ PAGES │ HEALTH │
├──────────┼──────────────────────────┼────────┼───────┼────────┤
│ cmabc123 │ Use The Index, Luke      │ READY  │ 42    │ ok     │
└──────────┴──────────────────────────┴────────┴───────┴────────┘
```

```json
{
  "items": [{ "id": "cmabc123", "title": "Use The Index, Luke", "status": "READY", "pageCount": 42, "health": "ok" }],
  "notFound": [],
  "timedOut": false
}
```

**Errors**

| Message | Fix |
| --- | --- |
| `{id}: not found in your library` | Check the id with `trove items list`. |
| `Timed out after {n}s with {count} still processing: {ids}` | Run the same command again. |

## trove items get

Prints the full text of one book to stdout, joined across pages. Use it to read a book you will then edit. It does not take `--json`.

**Usage**

```bash
trove items get ID[:PAGE] [--page N]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `ID[:PAGE]` | id, optionally with one page | required | Book to print. |
| `--page` | integer, 1 or more | whole book | Print just this page. Same as the inline `id:page` form. |

`read --pages` takes ranges. `get --page` takes one page.

**Example**

```bash
trove items get cmabc123 > book.md
```

**Output**

Text output only. The `version` the CLI reads here is the one you pass to `--expect-version` when you write back.

**Errors**

| Message | Fix |
| --- | --- |
| `Page {n} not found (document has {count} pages)` | Pick a page inside the book. |
| `Page numbers start at 1` | Use 1 or more. |
| `Page {n} is not available: this book is Pro-restricted for your account (preview only)` | The book is a preview on your plan. |
| `Invalid item ID '{id}'` | Use an id from `trove items list`. |

REST equivalent: [Reading API](https://docs.heytrove.ai/reference/api/items-read.md#get-full-content).