Command-line tool for working with mdbase collections. Validates, queries, and performs CRUD operations on markdown document collections. Can also execute Obsidian .base files.
Requires Node.js 22+.
npm install -g mdbase-cli
mdbase --helpThis installs both mdbase and mdbase-fzf on your PATH.
npm install --save-dev mdbase-cli
npx mdbase --helpgit clone https://github.com/callumalpass/mdbase-cli.git
cd mdbase-cli
npm ci
npm run build
node dist/cli.js --helpmdbase <command> [options]
Global option:
-C, --collection <alias>Run a command against a registered collection alias (frommdbase collections add).
| Command | Description |
|---|---|
validate |
Validate documents against their type schemas |
query |
Query documents with filters and sorting |
read |
Read a single document by path or ID |
create |
Create a new document |
update |
Update an existing document |
delete |
Delete a document |
rename |
Rename a document |
types |
List or inspect registered types |
migrate v0.3 |
Analyze or safely apply a v0.2-to-v0.3 migration |
| Command | Description |
|---|---|
base run |
Execute an Obsidian .base file |
| Command | Description |
|---|---|
init |
Initialize a new mdbase collection |
lint |
Lint documents for common issues |
fmt |
Format document frontmatter |
export |
Export documents to CSV or JSON |
import |
Import documents from CSV or JSON |
graph |
Show link graph between documents |
stats |
Print collection statistics |
watch |
Watch for file changes and re-validate |
diff |
Show differences between document versions |
schema |
Generate or inspect type schemas |
collections |
Manage named collection registry entries |
mdbase-fzf provides an interactive two-step picker powered by fzf:
- Choose a type (includes
untypefor files without a type). - Browse matching files with key fields (display/title-style fields are prioritized), preview, then open in your editor.
Requirements: fzf and jq on PATH.
mdbase-fzfValidate all documents in the current directory:
mdbase validate .Query documents of a given type:
mdbase query "status = published" --types note --sort created --limit 10query defaults to --format paths for fast output on large vaults. Use --format table for tabular display.
Execute an Obsidian .base file:
mdbase base run my-view.baseAnalyze a v0.2 collection without changing it, review the diff and JSON report, then apply that exact analysis with backup and rollback protection:
mdbase migrate v0.3 analyze --report migration-report.json
mdbase migrate v0.3 apply --report migration-report.json --yes
mdbase migrate v0.3 recover --backup .mdbase/migrations/v0.3-<id> --yesApply writes a durable backup manifest before replacing files and journals each
atomic replacement. recover verifies backup hashes before restoring an
interrupted or applied migration and reports any paths that require manual
recovery.
Analysis exits with status 2 when records are incompatible or features need
manual handling. Applying such a report additionally requires
--allow-partial.
Export to CSV:
mdbase export . --type note --format csv -o notes.csvInitialize and register a collection alias:
mdbase init --name Work --example-type task --register workinit creates a v0.3 collection by default. Use --spec-version 0.2.1 only when a legacy consumer requires the v0.2 type grammar.
List markdown files from all registered collections:
mdbase collections files --format paths| Project | Description |
|---|---|
| mdbase-workouts | Workout tracker with chat interface, built on mdbase |
mdbase-cli implements the mdbase specification.
MIT