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
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,statusandtoolsread the index, the troves and the tool catalog. Apart from creating an empty.trove/folder when it is missing, onlytoolsandaskwrite, and only to the tool catalog cache. - Build the index:
indexandimport-historicalwrite derived data into.trove/, which can be rebuilt at any time.recordandpatchappend event and patch records there, which cannot. - Write memory:
rememberwrites into your troves, which cannot be rebuilt, so it refuses duplicates and secrets. - Produce output:
shipwrites 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,patchandshipuse the current directory;ask,rememberand 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, onask,remember,tools,index,status,queryandship.--budget <TOKENS>: the token budget forask(default 1,500) andquery(default 200,000).--provider <PROVIDER>: the answer step forask:none(default),anthropic,ollamaorcmd. Environment:TROVE_PROVIDER.--model <MODEL>: the model for the provider. Theanthropicdefault isclaude-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. Default12.--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 ofconvention,decision,gotcha,preference,reference,project,snippet,context.--body <TEXT>: the entry body. Read from standard input when it is piped and--bodyis not given.--tags <A,B>: comma-separated tags.--section <SECTION>:conventions,memoryorcontext, overriding the route from--type. Project troves only.--update: replace an existing entry with the same slug, keeping itscreateddate.
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>orfind <terms>: ranked search over names and summaries.<name>,describe <name>orshow <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 fortools <name>.--limit <LIMIT>: the most rows;0for 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),singleorsite.--reindex <REINDEX>:auto(default, index only when no index exists),alwaysornever.--agent <AGENT>: run a coding agent review after the detectors:claude,codexorpi.--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. Default300.--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. Default200000.--json: printquery,estimated_tokens,stopped_earlyanditems.
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--providerand--model.ANTHROPIC_API_KEYorANTHROPIC_AUTH_TOKEN: credentials for--provider anthropic.ANTHROPIC_BASE_URLchanges the endpoint (defaulthttps://api.anthropic.com).OLLAMA_HOST(defaulthttp://localhost:11434) andOLLAMA_MODEL(defaultllama3.2): for--provider ollama.TROVE_LLM_CMD: the command for--provider cmd. Defaultclaude -p.TROVE_CACHE_DIR: where the tool catalog cache lives.HOME: locates~/.claude/troveand the default cache.
Exit status
0: success.1: a runtime error, printed asError: <message>.2: an argument error, reported by clap with a usage line, or a fail-closedship.