Skip to content
Trove

Trove / Reference

CLI reference

Every trove subcommand, argument, flag and environment variable on the main branch, taken from the clap parser in crates/trove-cli, with output formats.

On this page
  1. First principles
  2. Global options
  3. trove (no command)
  4. ask
  5. remember
  6. tools
  7. ship
  8. index
  9. status
  10. query
  11. import-historical
  12. record
  13. patch
  14. Environment variables
  15. Exit status

The trove command line interface (CLI) is built from the trove-cli crate. Its about line is “Memory, semantic and context layer for coding agents”. This page describes the current main branch; the binary reports version 0.2.0.

trove [OPTIONS] [COMMAND]

From inside a clone of the repository, cargo run -p trove-cli -- <args> runs the same binary. Run trove <command> --help for the built-in help of any command.

First principles

One binary does four kinds of work, and knowing which kind a command is tells you what it touches:

  • Read: ask, query, status and tools read the index, the troves and the tool catalog. Apart from creating an empty .trove/ folder when it is missing, only tools and ask write, and only to the tool catalog cache.
  • Build the index: index and import-historical write derived data into .trove/, which can be rebuilt at any time. record and patch append event and patch records there, which cannot.
  • Write memory: remember writes into your troves, which cannot be rebuilt, so it refuses duplicates and secrets.
  • Produce output: ship writes handoff docs (building the index first if none exists), and refuses to write if a secret survives.

Nothing leaves the machine unless you choose a provider for ask or an agent for ship.

Global options

These belong to trove itself but are accepted before or after the subcommand, so trove --repo ../app index and trove index --repo ../app are the same.

  • --repo <REPO>: the repository root. Without it, index, status, query, import-historical, record, patch and ship use the current directory; ask, remember and the interactive prompt walk up from the current directory to the nearest folder with .trove/ or .git.
  • --json: machine-readable JavaScript Object Notation (JSON) output, on ask, remember, tools, index, status, query and ship.
  • --budget <TOKENS>: the token budget for ask (default 1,500) and query (default 200,000).
  • --provider <PROVIDER>: the answer step for ask: none (default), anthropic, ollama or cmd. Environment: TROVE_PROVIDER.
  • --model <MODEL>: the model for the provider. The anthropic default is claude-opus-5-5. Environment: TROVE_MODEL.
  • -h, --help: print help.
  • -V, --version: print the version, trove 0.2.0.

trove (no command)

Opens the interactive prompt: load every source once, then answer each line as a question. Commands inside it: :tools <terms>, :tool <name>, :json, :budget <tokens>, :provider <name>, :reload, :help, :quit. See Asking questions.

ask

Answer a question with citations from troves, repository docs, the code index and installed tools, within a token budget.

trove ask [OPTIONS] <QUESTION>...
  • <QUESTION>...: the question. Several words are joined with spaces, so quotes are optional.
  • --limit <LIMIT>: the most sources to consider before budgeting. Default 12.
  • --no-tools: leave the installed tool catalog out.
  • --no-redact-nonsecret: keep emails, hosts, paths and other non-secret private details in provider prompts. Secrets are always redacted.

Text output is one or two lines per hit and a footer starting with --. JSON output has query, mode, sources, tokens, budget, matches and searched, plus provider, answer, answer_error, notes and redaction when they apply.

remember

Capture one entry into the trove: an entry file plus an index line.

trove remember [OPTIONS] --type <TYPE> <TITLE>...
  • <TITLE>...: the entry title. The slug is the title in lowercase kebab case.
  • --type <TYPE>: required. One of convention, decision, gotcha, preference, reference, project, snippet, context.
  • --body <TEXT>: the entry body. Read from standard input when it is piped and --body is not given.
  • --tags <A,B>: comma-separated tags.
  • --section <SECTION>: conventions, memory or context, overriding the route from --type. Project troves only.
  • --update: replace an existing entry with the same slug, keeping its created date.

It writes to the project trove when <repo>/.claude/trove/INDEX.md exists, otherwise to ~/.claude/trove. Routing: convention and preference to conventions/, context to context/, everything else to memory/. It refuses entries that look like they contain secrets. Output: Remembered '<title>' -> <path> (<section>). With --json: slug, path, section, updated. See Project troves.

tools

List, search and describe installed command line tools.

trove tools [OPTIONS] [ARGS]...
  • No arguments, or list: list every tool.
  • search <terms> or find <terms>: ranked search over names and summaries.
  • <name>, describe <name> or show <name>: describe one tool.
  • open <name>: open its man page.
  • refresh: refresh the cache and print what changed.
  • --probe: run each tool’s --help, guarded, with a 1.5-second timeout, when it has no man summary.
  • --full: rescan every folder, ignoring the cache.
  • --man: open the man page for tools <name>.
  • --limit <LIMIT>: the most rows; 0 for all. The list defaults to all, search to 20.

See Tool catalog.

ship

Turn a project and its trove into developer handoff docs, with secrets and private information removed before anything is written.

trove ship [OPTIONS]
  • --repo <REPO>: the repository to ship. Default ..
  • --out <OUT>: the output folder. Default <repo>/.trove/ship.
  • --format <FORMAT>: folder (default), single or site.
  • --reindex <REINDEX>: auto (default, index only when no index exists), always or never.
  • --agent <AGENT>: run a coding agent review after the detectors: claude, codex or pi.
  • --agent-cmd <AGENT_CMD>: a shell command for the review; it gets the prompt on standard input and prints a JSON array.
  • --agent-timeout <SECONDS>: seconds per agent call. Default 300.
  • --dry-run: redact and print the report without writing files.
  • --force: write into a non-empty folder that ship did not create.
  • --no-local-identity: do not treat your login name and home folder as private.
  • --json: print the redaction report as JSON.
  • --list-detectors: list the built-in detectors and exit.

Exit codes: 0 success, 1 error, 2 fail closed (a high-confidence secret survived; nothing written). The trove-ship binary takes the same flags. See Handoff docs with trove ship.

index

Index the repository: symbols, modules, subsystems, architecture.

trove index [--full]
  • --full: ignore the existing index and rebuild everything. Without it the run is incremental by intent; see Indexing a repository for how that behaves in the current code.

Output:

Indexed <files> files, <symbols> symbols, <modules> modules, <subsystems> subsystems (<n> stale rebuilt)

With --json: files_scanned, symbols, modules, subsystems, stale_rebuilt.

status

Show index status.

trove status

Reads .trove/manifest.json and prints:

Trove v0.2.0
Repo:   /absolute/path/to/repo
Indexed: 2026-10-25T03:48:26.940491+00:00
Counts: 1372 symbols, 134 modules, 3 subsystems

Without an index it prints No index found. Run: trove index. With --json it prints the manifest, or null without an index.

query

Assemble progressive context for a query within a token budget.

trove query [OPTIONS] <QUERY>
  • <QUERY>: the task in plain words. Quote it when it has spaces.
  • --budget <TOKENS>: total token budget. Default 200000.
  • --json: print query, estimated_tokens, stopped_early and items.

See Retrieval levels for the retrieval order and both output formats.

import-historical

Import L5 historical entries from ~/.claude/trove or ./.claude/trove.

trove import-historical

Reads <repo>/.claude/trove and then $HOME/.claude/trove, each only if it contains an INDEX.md. Every .md and .json entry, flat or in a section, becomes an object with id historical:<slug>, and each INDEX.md is stored as repository:index. It only reads the trove folders and writes into .trove/.

Output:

Imported <n> historical entries

record

Record an execution memory event in .trove/execution.json.

trove record open <PATH>
trove record search <QUERY>
trove record command <CMD>
  • open <PATH>: a file was opened.
  • search <QUERY>: a search was run.
  • command <CMD>: a command was run.

Each event is stored with a timestamp in Coordinated Universal Time (UTC). The file keeps the most recent 500 events. Output: Recorded execution event.

Example execution.json:

{
  "events": [
    { "type": "opened_file", "path": "src/main.rs", "at": "2026-09-29T19:37:22.133166Z" },
    { "type": "command", "cmd": "cargo test", "at": "2026-09-29T19:37:22.145058Z" }
  ]
}

patch

Record a patch: before and after hash plus a reason, appended to .trove/patches.json.

trove patch --reason <REASON> <PATH> <BEFORE> <AFTER>
  • <PATH>: the file that changed.
  • <BEFORE>, <AFTER>: hashes of the file before and after. Any strings are accepted.
  • --reason <REASON>: required. Why the change was made.

The record id is patch:<path>:<unix timestamp>. Output: Recorded patch <id>. trove ship lists the latest 30 patches in its decisions document.

trove patch src/auth.rs 3f2a9c 81be04 --reason "fix session expiry check"

Environment variables

  • TROVE_PROVIDER, TROVE_MODEL: defaults for --provider and --model.
  • ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN: credentials for --provider anthropic. ANTHROPIC_BASE_URL changes the endpoint (default https://api.anthropic.com).
  • OLLAMA_HOST (default http://localhost:11434) and OLLAMA_MODEL (default llama3.2): for --provider ollama.
  • TROVE_LLM_CMD: the command for --provider cmd. Default claude -p.
  • TROVE_CACHE_DIR: where the tool catalog cache lives.
  • HOME: locates ~/.claude/trove and the default cache.

Exit status

  • 0: success.
  • 1: a runtime error, printed as Error: <message>.
  • 2: an argument error, reported by clap with a usage line, or a fail-closed ship.