| name | means |
| description | Query collections of Markdown documents with YAML frontmatter using the `means` CLI. Use when the user asks you to search, list, or inspect a directory of Markdown notes/docs (especially when frontmatter fields like `status`, `tags`, `title` are involved), or when `MEANS_DIR` is set in the environment. Output is JSON, so it's well-suited for programmatic use. |
means
means is a CLI for querying directories of Markdown files with YAML frontmatter. On every invocation it walks the target directory, parses frontmatter, and builds a fresh in-memory Bleve index — no server, no config.
Picking the directory
Every command needs to know which directory to work in.
- Prefer the
MEANS_DIR env var if it is already set — don't override it.
- Otherwise pass
--dir <path> explicitly. If neither is set, the command errors.
export MEANS_DIR=./notes
means list
means --dir ./other list
Commands
list — enumerate documents
Prints a JSON array of { path, frontmatter } for every Markdown file.
means list
means list --include-body
Use this when you need an overview of what's in the directory or want to scan frontmatter fields across all docs.
search — Bleve query string search
Runs a Bleve query string across paths, frontmatter, and content. Returns { total, hits: [{ path, score, frontmatter }] }.
means search rutabaga
means search 'status:draft'
means search '+tags:overview +status:published'
means search '+status:draft -tags:archived'
means search rutabaga --limit 5 --include-body
Query tips:
- Field syntax:
field:value. Fields come from frontmatter keys plus path and content.
- Phrases:
"exact phrase".
- Combining terms: bare terms are OR-ed (any match scores). Prefix with
+ to require a term (AND) and - to exclude it. Bleve's query string does not treat the words AND / OR as operators — they get tokenized as content, so status:draft AND priority:high does not mean what it looks like.
- Default
--limit is 20. Raise it with --limit N when you expect more hits.
- Add
--include-body only when you actually need the full Markdown — otherwise the output stays compact.
Typical flows
"What's in this notes directory?" → means list (or pipe through jq to pluck fields).
"Find drafts tagged X." → means search '+status:draft +tags:X'.
"Which docs mention Foo?" → means search Foo — then means search Foo --include-body --limit 3 to read the relevant ones.
Inspecting a single match: once you have a path from search, read the file directly with the Read tool instead of re-running means with --include-body.
Output handling
All output is JSON on stdout; errors go to stderr with a non-zero exit. Parse with jq when you need to extract fields:
means list | jq -r '.[].path'
means search 'status:draft' | jq '.hits[] | {path, title: .frontmatter.title}'
What means does not do
- It does not write, create, update, or delete documents — it's read-only. To modify Markdown files, use normal file tools (
Edit, Write).
- It does not persist an index between runs; every invocation re-scans the directory. That's fine for directories up to a few thousand docs.
- It is not a full-text editor, renderer, or git wrapper.
