smolbren is an ontology-first search CLI for Markdown vaults. It combines BM25 full-text search with a Cypher-queryable knowledge graph built from your notes’ frontmatter types and wikilink edges. Every subcommand is designed to compose well with other tools — all output is machine-readable JSON that you can pipe directly to jq, scripts, or AI agents.
Global flags
These flags are accepted by every subcommand and must be placed before the subcommand name.The name of the registered vault to operate on. Overrides the configured
default vault for this invocation. If omitted and a default vault is
configured, the default is used automatically. Use
smolbren vault list to
see registered vault names.Path to the smolbren config file. Defaults to
~/.smolbren/config.json. Use
this to maintain multiple independent configurations, for example in CI
environments or when running tests against an isolated vault.Command summary
| Command | Description |
|---|---|
vault | Register, list, and remove Markdown vaults |
index | Build or update the search index for a vault |
search | BM25 full-text search over note titles and bodies |
query | Execute Cypher queries over the note knowledge graph |
get | Fetch a single note by ID, optionally including its body |
links | List outgoing wikilink edges from a note |
backlinks | List incoming wikilink edges pointing to a note |
types | List all note types present in the vault with counts |
edges | List all edge relationship types with counts |
Output contract
All successful output is written to stdout as a single line of JSON, with no trailing newline except what your terminal adds. The exact shape varies per command and is documented on each command’s page. All errors are written to stderr as a single-line JSON object and the process exits with a non-zero code:error field is a human-readable message. The code field is a stable machine-readable identifier. See the Exit Codes page for the full table of codes and their meanings, and the Output Format page for field-by-field documentation of every command’s response shape.