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, 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.

Working from the source tree instead? 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

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 ~/vault

Proposing 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 ~/vault

The 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.

Related