mdvdb CLI Documentation
mdvdb is a filesystem-native vector database built around Markdown files. It provides semantic and lexical retrieval, graph analysis, typed frontmatter queries, computed fields, Shards, Topics, and more from one local CLI.
Getting Started
| Page | Description |
|---|
| Installation | Install mdvdb via cargo, GitHub releases, or from source |
| Quick Start | Go from zero to your first search in 5 minutes |
| Agent Skills | Use 15 mdvdb workflows with Claude Code, Codex, Gemini CLI, Cursor, or GitHub Copilot |
| Configuration | Environment variables, config files, and resolution order |
| Tesseract desktop companion | Visual editing, tables, graphs, Shards, Topics, and agent tooling |
| Shell Completions | Set up tab completions for bash, zsh, fish, and PowerShell |
Command Reference
All CLI commands are documented individually under Commands.
| Category | Commands | Description |
|---|
| Core | search, ingest, status, collection | Index, retrieve, and query Markdown records |
| Setup | init, config, embedding, shards, doctor | Initialize, configure, verify providers, and diagnose |
| Inspection | info, schema, clusters, tree, get | Explore Collection or Shard analysis and metadata |
| Graph | links, backlinks, orphans, edges, graph | Navigate the link graph between files |
| Automation | watch, modules | React to file changes and materialize computed metadata |
Concepts
Deeper explanations of how mdvdb works under the hood.
| Page | Description |
|---|
| Frontmatter as structured data | SQL-like row, column, filter, sort, and pagination model—and its limits |
| Relations | Foreign-key-like Markdown references and depth-one population |
| Computed Fields | Formula, Lookup, and Rollup fields materialized into frontmatter |
| Shards and Topics | Named folder lenses, local analysis, communities, and multi-label Topics |
| Search Modes | Hybrid, semantic, lexical, and edge search explained |
| Embedding Providers | Supported local and cloud provider setup |
| Chunking | How Markdown files are split into chunks for embedding |
| Link Graph | Link extraction, backlinks, orphans, and semantic edges |
| Time Decay | Time-based scoring decay for search results |
| Clustering | Automatic communities and user-defined Topics |
| Ignore Files | .gitignore, .mdvdbignore, and built-in exclusions |
| Index Storage | The .markdownvdb/ directory and binary index format |
Use cases
| Playbook | What it builds |
|---|
| LLM wiki | Retrieval-ready handbooks, product docs, runbooks, and decisions |
| AI memory layer | Durable Markdown memory with configurable recency decay |
| Knowledge operations | Linked project, client, research, or workflow records with computed state |
Command Overview
graph LR
subgraph Setup
init["mdvdb init"]
config["mdvdb config"]
embedding["mdvdb embedding"]
shards["mdvdb shards"]
doctor["mdvdb doctor"]
end
subgraph Indexing
ingest["mdvdb ingest"]
watch["mdvdb watch"]
end
subgraph Search
search["mdvdb search"]
collection["mdvdb collection"]
end
subgraph Inspection
status["mdvdb status"]
info["mdvdb info"]
schema["mdvdb schema"]
clusters["mdvdb clusters"]
tree["mdvdb tree"]
get["mdvdb get"]
modules["mdvdb modules"]
end
subgraph Graph
links["mdvdb links"]
backlinks["mdvdb backlinks"]
orphans["mdvdb orphans"]
edges["mdvdb edges"]
graphCmd["mdvdb graph"]
end
init --> ingest
ingest --> search
ingest --> collection
ingest --> status
ingest --> info
ingest --> modules
watch -.-> ingest
search --> get
config --> embedding
links --> backlinks
Global Options
The first four flags are accepted before or after any subcommand. --version is top-level only.
| Flag | Short | Description |
|---|
--verbose | -v | Increase log verbosity (-v info, -vv debug, -vvv trace) |
--root <PATH> | | Project root directory (defaults to current directory) |
--no-color | | Disable colored output |
--json | | Output results as JSON |
--version | | Print version information with logo; use mdvdb --version |
Running mdvdb with no subcommand prints a logo and usage hint.
See Also
Tesseract