Source: https://velofy.co/trove/tools/ [Trove](https://velofy.co/trove/) / Guides # Tool catalog How trove tools discovers every command line tool installed on macOS or Linux, summarizes it from man pages, caches the catalog, and searches or describes it. `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 ` --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 ` 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 ` shows the first `n`; the default for the list is all of them. * `trove tools search ` (or `find`): rank tools by name, then by summary words. Default `--limit` 20. * `trove tools `, `describe ` or `show `: the tool’s source, summary, path, shadowed copies, man page and the first 14 lines of its `--help`. With `trove tools `, an unknown name prints the closest matches; `describe` and `show` report an error instead. * `trove tools open `, 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 ` searches and `:tool ` describes, with a limit of 15 rows. See [Asking questions](https://velofy.co/trove/ask/).