trove items, reading

These commands find books and read their text. Writing commands are on trove items: write. Each book you open counts as one read.

Quick reference#

trove items list#

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

Usage

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

Arguments and flags

Example

trove items list --shelf backend --json

Output

┌──────────┬─────────────────────┬───────┬────────┬────────┬────────┐
│ 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

REST equivalent: List items.

trove items toc#

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

Usage

trove items toc IDS [--json]

Arguments and flags

Example

trove items toc cmabc123

Output

============================================================ 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

REST equivalent: Reading API.

trove items read#

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

Usage

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

Arguments and flags

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

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

Output

────────────────────────────────────────────────────────────
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

REST equivalent: Reading API.

trove items status#

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

Usage

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

Arguments and flags

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

trove items status cmabc123 --wait --timeout 600

Output

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

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

Errors

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

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

Arguments and flags

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

Example

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

REST equivalent: Reading API.