tools-mdbase

Original：🇺🇸 English
Translated

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.

8installs
Sourcenikhilmaddirala/gtd-cc
Added on

NPX Install

npx skill4agent add nikhilmaddirala/gtd-cc tools-mdbase

Tags

Translated version includes tags in frontmatter
mdbasemarkdown-databasecli-toolyaml-frontmatterknowledge-management

SKILL.md Content

View Translation Comparison →

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

NamespaceTypes
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:
yaml
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:
bash
# Run from repo root
npx mdbase <command> [options]

Create notes

bash
# 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

bash
# 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

bash
# 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

bash
# 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

bash
# 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

bash
# 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

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

Run Obsidian bases

bash
# 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:
yaml
global-type: misc-recipe
  1. No schema needed initially - mdbase allows unknown types

Formal type definition

Create 
90-system/_types/misc-example.md
:
yaml
---
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

bash
# 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

bash
# 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

bash
# 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+:
bash
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