tools-mdbase

name	tools-mdbase
description	This skill should be used when the user asks to "validate my collection", "query markdown files", "create mdbase type", "mdbase schema", "init mdbase", "mdbase validate", "mdbase query", or mentions mdbase, typed markdown collections, or frontmatter schemas.

mdbase

Work with mdbase collections: typed, queryable markdown file databases with YAML frontmatter schemas.

Monorepo vault setup

This vault is configured as an mdbase collection:

• Config: ./mdbase.yaml
• Types: ./90-system/_types/
• Schema docs: ./90-system/docs/mdbase-schema.md

Available types

Namespace	Types
journals-*	journals-daily, journals-weekly, journals-quarterly, journals-yearly
zettel-*	zettel-source, zettel-publication, zettel-idea, zettel-fleeting
entity-*	entity-person, entity-organization
para-*	para-project, para-area, para-resource, para-task
misc-*	misc-software, misc-workflow, and any ad-hoc types

Type matching

All types use global-type field for matching:

global-type: zettel-source

Duck-typing fallback available for migration (e.g., files with source-url + source-title match zettel-source).

CLI usage

Run from monorepo root:

# Run from repo root
npx mdbase <command> [options]

Create notes

# Create a source note
npx mdbase create --type zettel-source

# Create with fields
npx mdbase create --type zettel-source \
  --source-title "Article Title" \
  --source-url "https://example.com" \
  --zettel-status drafted

# Create a task
npx mdbase create --type para-task \
  --para-status todo \
  --para-priority p2

# Create a project
npx mdbase create --type para-project \
  --para-status active \
  --para-area "[[Career]]"

# Create a person entity
npx mdbase create --type entity-person \
  --entity-name "Jane Doe"

# Create a publication
npx mdbase create --type zettel-publication \
  --pub-title "Episode Title" \
  --pub-type podcast \
  --zettel-status drafted

Query notes

# All active projects
npx mdbase query "global-type = para-project AND para-status = active"

# Unreviewed sources
npx mdbase query "global-type = zettel-source AND zettel-status = drafted"

# Tasks by priority
npx mdbase query "global-type = para-task AND para-priority = p1"

# Overdue tasks
npx mdbase query "global-type = para-task AND para-due-date < 2026-02-06"

# YouTube sources
npx mdbase query "source-platform = youtube" --types zettel-source

# Projects sorted by deadline
npx mdbase query "para-status = active" --types para-project --sort para-deadline

# Limit results
npx mdbase query "global-type = zettel-source" --limit 10 --sort "-source-fetched-date"

Validate

# Validate entire vault
npx mdbase validate .

# Validate specific folder
npx mdbase validate 20-zettel/
npx mdbase validate 30-para/

# Validate single file
npx mdbase validate 30-para/31-projects/example-project.md

Update notes

# Mark source as reviewed
npx mdbase update 20-zettel/sources/article.md --set "zettel-status=reviewed"

# Complete a task
npx mdbase update 30-para/tasks/my-task.md --set "para-status=completed"

# Update project deadline
npx mdbase update 30-para/31-projects/project.md --set "para-deadline=2026-03-01"

Read and inspect

# Read a file
npx mdbase read 30-para/31-projects/example-project.md

# Get vault statistics
npx mdbase stats .

# Visualize links
npx mdbase links . --format dot > graph.dot

Export and import

# Export projects to CSV
npx mdbase export . --type para-project --format csv -o projects.csv

# Export sources to JSON
npx mdbase export . --type zettel-source --format json -o sources.json

# Import tasks from CSV
npx mdbase import tasks.csv --type para-task

Rename with link updates

# Rename file and update all [[wikilinks]]
npx mdbase rename old-name.md new-name.md

Run Obsidian bases

# Execute a .base query file
npx mdbase base run 90-system/bases/zettel-sources.base
npx mdbase base run 90-system/bases/para-tasks.base

Adding new types

Quick ad-hoc type

1. Use misc-* prefix in frontmatter:

global-type: misc-recipe

2. No schema needed initially - mdbase allows unknown types

Formal type definition

Create 90-system/_types/misc-example.md:

---
name: misc-example
matchFields: [global-type]
fields:
  global-type:
    type: enum
    values: [misc-example]
    required: true
  custom-field:
    type: string
    required: false
---

# misc-example

Description of when to use this type.

Common workflows

Process inbox item

# Query inbox items (untyped files in 00-inbox)
ls 00-inbox/

# Create typed note from inbox content
npx mdbase create --type zettel-source --source-title "..." --source-url "..."

# Or create task
npx mdbase create --type para-task --para-status todo

Weekly review queries

# Unreviewed sources
npx mdbase query "zettel-status = drafted" --types zettel-source

# Active projects
npx mdbase query "para-status = active" --types para-project

# Todo tasks
npx mdbase query "para-status = todo" --types para-task --sort para-priority

# Orphan ideas (no sources linked)
npx mdbase query "zettel-sources = []" --types zettel-idea

Bulk operations

# Archive old drafted sources
npx mdbase query "zettel-status = drafted AND source-fetched-date < 2025-01-01" \
  --types zettel-source --format paths | \
  xargs -I {} npx mdbase update {} --set "zettel-status=archived"

Troubleshooting

Node.js version

mdbase-cli requires Node.js 22+:

node --version

Validation errors

Check:

1. Valid YAML frontmatter (between --- markers)
2. Required fields present for the type
3. Enum values match allowed values
4. Date format is YYYY-MM-DD

Type not matching

1. Verify global-type field value matches type name exactly
2. Check 90-system/_types/ for valid type names
3. For duck-typing, ensure characteristic fields are present

References

• Schema docs: 90-system/docs/mdbase-schema.md
• Type definitions: 90-system/_types/
• Obsidian bases: 90-system/bases/
• mdbase spec: https://github.com/callumalpass/mdbase-spec
• mdbase CLI: https://github.com/callumalpass/mdbase-cli