Docs/Connecting to Minerva/CLI use
CLI use
The Minerva CLI gives headless, scriptable access to a thoughtbase from your shell — the same core the app runs on, so it works with the app closed. Every result is printed as JSON on standard output, so it pipes straight into jq or feeds an agent directly.
Getting the command
If you installed Minerva from the download on a Mac, choose Help → Install ‘minerva’ Command in PATH… in the app. That writes a minerva launcher to ~/.local/bin — the app runs its own bundled Node, so there's nothing else to install. If ~/.local/bin isn't on your PATH, the dialog shows how to add it, and gives the full path to use for MCP clients.
The menu item is macOS-only for now. On other platforms, or working from the source tree, build and link it:
pnpm cli:build # builds .vite/build/cli.js
pnpm link --global # exposes it globally as `minerva`Either way, minerva then works anywhere. Point any command at a thoughtbase with --project <path> — it defaults to the current directory.
minerva <command> [args] [--project <path>]Commands
query <sparql>minerva:, dc:, and the rest without declaring them.sql <sql>search <text>--limit <n>, default 20).grep <pattern>--regex treats it as a regular expression, --case-sensitive matches case exactly, and --limit <n> caps the matches returned (default 50, at most 200).semantic <text>read <path>context <topic>propose-note <path>Grounded JSON output
Every result is grounded and printed as JSON, so it composes with the rest of your tools — query bindings carry node identifiers, search hits carry the note path, and read echoes the path back.
# What do I already know about photosynthesis?
minerva search photosynthesis --project ~/vault | jq '.hits[].relativePath'
# Every note with a title, alphabetized.
minerva query \
'SELECT ?title WHERE { ?n a minerva:Note ; dc:title ?title } ORDER BY ?title' \
--project ~/vaultProposing a note
External tools never write your thoughtbase directly. propose-note files a note as a pending proposal through Minerva's approval engine — the same gate the built-in AI uses — stamped with who proposed it. Nothing lands until you review and approve it in Minerva's Proposals panel (see Conversations).
cat draft.md | minerva propose-note notes/idea.md --by cli --project ~/vaultThe body comes from stdin, so it composes with anything upstream. --by <id> records who proposed it (default cli), and that attribution survives a reindex — a note proposed while the app was closed still shows up, and stays attributed, once you reopen it.
Like proposals from an outside agent, it can't target .minerva/, another hidden folder, or anything outside the thoughtbase.
The CLI checks whether Minerva has the same thoughtbase open (the app leaves a .minerva/runtime.json marker while it does). If it has, propose-note and semantic are handed to the running app: the proposal goes through the app's own approval gate and appears in the Proposals panel right away, and semantic search uses the app's current index. If it hasn't, both run directly against the files, and the proposal is waiting the next time you open the thoughtbase. Every other command reads the thoughtbase directly either way, as it is when you run it.