---
title: "CLI reference"
description: "Use when you run Trove from a terminal or a coding agent and need the command groups, global flags, environment variables and common errors of the trove CLI."
url: https://docs.heytrove.ai/reference/cli
updated: 2026-10-01
---

# CLI reference

> Load this page when: you need to run a trove command and want to find its group page, a global flag or an environment variable

## For agents

- Read a book in three steps. Run trove items list, then trove items toc, then trove items read with a page range.
- Add --json to get machine-readable output, except on the commands listed under Global flags.
- Add --no-session to read-only calls that must not join a research session.

The CLI is named `trove`. It talks to the same REST API as every other client, so anything you can do here you can also script over HTTP.

## Install

Install the binary with the steps on [Install Trove](https://docs.heytrove.ai/install.md). The old name was `ck`. It still runs, prints a notice and forwards to `trove`, so use `trove` in new scripts.

## How an agent reads a book

Read in three steps. Each step narrows the next one, so an agent never pulls a whole book to answer one question.

| Step | Command | What it gives you |
| --- | --- | --- |
| 1 | `trove items list --no-session` | Book ids and titles |
| 2 | `trove items toc <id>` | Chapters with page ranges |
| 3 | `trove items read "<id>:10-20"` | The text of those pages |

Each book you open counts as one read. See [Plans and limits](https://docs.heytrove.ai/reference/plans-and-limits.md).

## Command groups

| Group | Page | What for |
| --- | --- | --- |
| `trove auth` | [trove auth](https://docs.heytrove.ai/reference/cli/auth.md) | Sign in, sign out, show your account |
| `trove items` list, toc, read, status, get | [trove items: read](https://docs.heytrove.ai/reference/cli/items.md) | Find books and read pages |
| `trove items` add, create, import, put, append, history, restore, remove, reprocess, enrich, flag | [trove items: write](https://docs.heytrove.ai/reference/cli/items-writing.md) | Add and edit books |
| `trove items` report-gap, gaps, resolve-gap, restore-gap | [trove items: gaps](https://docs.heytrove.ai/reference/cli/items-gaps.md) | Reader requests for your books |
| `trove shelf`, `trove init` | [trove shelf](https://docs.heytrove.ai/reference/cli/shelf.md) | Group books and pin a project shelf |
| `trove ms` | [trove ms](https://docs.heytrove.ai/reference/cli/ms.md) | Manuscripts |
| `trove marketplace` | [trove marketplace](https://docs.heytrove.ai/reference/cli/marketplace.md) | Browse and add public books |
| `trove team` | [trove team](https://docs.heytrove.ai/reference/cli/team.md) | Members, departments and shared books |
| `trove setup`, `install`, `update`, `version`, `scan`, `welcome`, `tour` | [trove setup](https://docs.heytrove.ai/reference/cli/setup.md) | Install into your agents and keep the binary current |
| `trove config` | [trove config](https://docs.heytrove.ai/reference/cli/config.md) | Personal settings |
| `trove sources` | [trove sources](https://docs.heytrove.ai/reference/cli/sources.md) | Saved sources |
| `trove value` | [trove value](https://docs.heytrove.ai/reference/cli/value.md) | What your agents read |
| `trove report` | [trove report](https://docs.heytrove.ai/reference/cli/report.md) | Send a bug report or idea |

## Global flags

| Flag | Meaning |
| --- | --- |
| `--json` | Print machine-readable JSON. |
| `--version`, `-V` | Print the installed version. With `--json`, print `current`, `latest`, `up_to_date` and `source`. |
| `--help`, `-h` | Print help for any command. |

`--json` is global, but some commands print text only. They ignore the flag.

| Group | Commands that print text only |
| --- | --- |
| `items` | add, remove, enrich, flag, reprocess, get, put, restore, import, append, report-gap, resolve-gap |
| `ms` | update, archive |
| `config` | get, set |
| `auth` | login, logout |

`trove items history` and `trove config show` take their own `--json`. `trove value` takes `--format markdown` or `--format json`.

### Flags for agents and scripts

`--no-session` does not show in `--help`. It stops a read from joining the current research session. Without it, the CLI uses `--session`, else the session file, else no session.

```bash
trove items list --no-session --json
```

## Environment variables

| Variable | Effect |
| --- | --- |
| `TROVE_API_URL` | Send requests to another server, such as a preview environment. |
| `TROVE_NO_AUTO_UPDATE` | Set to `1` to stop background updates of the binary and the skills. |
| `TROVE_NO_UPDATE_CHECK` | Set to `1` to stop the version check. |
| `TROVE_NO_CLIENT_TELEMETRY` | Set to `1` to stop sending the name of the agent that ran the command. |

The older `CK_NO_AUTO_UPDATE`, `CK_NO_UPDATE_CHECK` and `CK_NO_CLIENT_TELEMETRY` still work.

## Common errors

| Message | Fix |
| --- | --- |
| `Not authenticated. Run 'trove auth login' first.` | Sign in with `trove auth login`, or `trove auth login --with-token` on a server. See [trove auth](https://docs.heytrove.ai/reference/cli/auth.md). |
| `Invalid or revoked API key` | The key was revoked. Create a new one in [API keys](https://docs.heytrove.ai/reference/api-keys.md) and sign in again. |
| `Trove: your agent has used all {limit} reads for {month}. Reads reset on {date}. Pro has unlimited reads: {host}/billing` | Stop reading. Do not retry. Tell the user. See [Errors](https://docs.heytrove.ai/reference/api.md#errors). |