Tool catalog

trove tools lists, searches and describes the command line tools installed on the machine. trove ask searches the same catalog alongside your troves and code, so a question about pretty-printing JavaScript Object Notation (JSON) can surface jq.

trove tools                     # list every installed tool with a one-line summary
trove tools search json         # ranked search over names and summaries
trove tools jq                  # describe: path, summary, man page, --help excerpt
trove tools jq --man            # open the man page
trove tools refresh             # show what the incremental refresh did
trove tools refresh --probe     # also collect summaries from --help

First principles

An agent that does not know a tool is installed reinvents it, or guesses its flags. The facts it needs already exist on disk: the directories on $PATH and the package manager folders say what is installed, and man pages say what each tool does. Reading them is cheap; running a tool to ask it is not always safe, because some programs ignore --help and do their normal work.

So the catalog is built from directory listings and man pages, cached, and refreshed only for directories that changed. Running a tool’s --help is opt-in for the whole catalog, and automatic only for the one tool you ask about.

Where tools are found

Discovery scans $PATH first, in order, so a tool that appears twice resolves to the same copy your shell would run; later copies are reported as shadowed. Then it adds package manager folders that are often missing from non-login shells:

• Homebrew: $HOMEBREW_PREFIX, /opt/homebrew, /usr/local and Linuxbrew.
• Cargo: $CARGO_HOME/bin or ~/.cargo/bin.
• ~/.local/bin.
• npm: $NPM_CONFIG_PREFIX, ~/.npm-global, ~/.npm-packages and Volta.
• pnpm: $PNPM_HOME and its default folders.
• Bun: ~/.bun/bin.
• Go: $GOPATH/bin and ~/go/bin.

Each tool is labelled with where it came from: system, brew, cargo, local, npm, pnpm, bun or go. An nvm folder is not scanned on its own, but when it is on $PATH its tools are labelled npm.

Summaries

The one-line summary comes from the tool’s man page, read directly from disk. Plain and gzip-compressed pages are read, in both the man and mdoc formats. A tool without a man page has no summary until it is probed.

--probe runs <tool> --help for tools without a man summary. Because some programs act instead of printing help, probing is guarded:

• a denylist skips shells, editors, pagers and system commands such as reboot, shutdown, sudo, dd and mkfs,
• the tool gets no standard input and 1.5 seconds,
• it runs in an empty scratch folder with HOME and the other per-user folders pointed there.

trove tools <name> runs --help for that one tool, since you asked about it, and stores the summary it finds.

The cache

The catalog is cached in tools.json under:

• macOS: ~/Library/Caches/trove/
• Linux: $XDG_CACHE_HOME/trove/, or ~/.cache/trove/
• anywhere: $TROVE_CACHE_DIR when set

Each run checks the modification time of every bin folder and rescans only the folders that changed. Inside those, binaries that did not change keep their cached summary. --full ignores the cache and rescans everything.

trove tools refresh

1924 tools in 14 dirs | 14 rescanned, +1931 -0 entries, 1320 man summaries, 0 --help probes
-- cache ~/Library/Caches/trove/tools.json

Commands

• trove tools or trove tools list: list every tool. --limit <n> shows the first n; the default for the list is all of them.
• trove tools search <terms> (or find): rank tools by name, then by summary words. Default --limit 20.
• trove tools <name>, describe <name> or show <name>: the tool’s source, summary, path, shadowed copies, man page and the first 14 lines of its --help. With trove tools <name>, an unknown name prints the closest matches; describe and show report an error instead.
• trove tools open <name>, or --man on a describe: open the man page. Without one, it prints a note and shows the --help excerpt.
• trove tools refresh: run the refresh and print what it did.

Every form accepts --json.

A name always wins over a subcommand word it does not match: trove tools ls describes the ls program. To list the catalog, use trove tools or trove tools list.

In the interactive prompt

Inside trove with no arguments, :tools <terms> searches and :tool <name> describes, with a limit of 15 rows. See Asking questions.