mdbase-tasknotes CLI

mdbase-tasknotes (mtn) is a standalone command-line tool for managing TaskNotes tasks directly on markdown files. It uses mdbase to read and write task files and tasknotes-nlp-core for natural language parsing.

← Back to APIs & Integration

When to use this vs tasknotes-cli

TaskNotes ships with tasknotes-cli (tn), which communicates with the Obsidian plugin over its HTTP API. mdbase-tasknotes operates directly on the markdown files instead.

	tn (tasknotes-cli)	mtn (mdbase-tasknotes)
Requires Obsidian	Yes — plugin must be running with API enabled	No
Operates on	HTTP API	Markdown files directly via mdbase
Use when	Obsidian is open and you want live sync	Obsidian is closed, on a server, or in scripts
Time tracking	Via plugin API	Via frontmatter timeEntries
Task creation	NLP via API	NLP via bundled tasknotes-nlp-core
Install	npm install -g tasknotes-cli	npm install -g mdbase-tasknotes

Use mtn when:

• Obsidian isn't running or isn't available (headless servers, SSH sessions, CI pipelines)
• You want to manage tasks from the terminal without any background process
• You're scripting task creation or querying in shell workflows
• You're on a machine where Obsidian isn't installed

Both tools read and write the same task files, so they can be used interchangeably on the same vault.

Install

npm install -g mdbase-tasknotes

Setup

Using an existing TaskNotes vault

If you already use TaskNotes with mdbase spec generation enabled (Settings → Integrations → Enable mdbase spec), point mtn at your vault root:

mtn config --set collectionPath=/path/to/your/vault

The plugin generates mdbase.yaml and _types/task.md automatically — mtn reads these to understand your task schema, including your custom statuses and priorities.

Creating a standalone collection

To create a new collection without Obsidian:

mtn init ~/tasks
mtn config --set collectionPath=~/tasks

This generates mdbase.yaml, _types/task.md, and a tasks/ folder with sensible defaults (statuses: open, in-progress, done, cancelled; priorities: low, normal, high, urgent).

Creating tasks

Create tasks using natural language. Tags, contexts, projects, dates, priorities, and recurrence are extracted automatically:

mtn create "Buy groceries tomorrow #shopping @errands"
mtn create "Write quarterly report due friday #work +quarterly-review"
mtn create "Call dentist high priority @phone"
mtn create "Water plants every monday #home"

Supported patterns

Pattern	Example	Extracted as
#tag	#shopping	Tag
@context	@errands	Context
+project	+quarterly-review	Project (stored as wikilink)
Date words	tomorrow, friday, next week	Due date
Priority words	high priority, urgent	Priority
Recurrence	every day, weekly, every monday	Recurrence rule
Estimate	~30m, ~2h	Time estimate

The NLP parser reads your collection's status and priority enum values from _types/task.md, so any custom values you define there are automatically recognized.

Querying tasks

List tasks

# Default: open tasks ordered by due date
mtn list

# Filter by status, priority, or tag
mtn list --status in-progress
mtn list --priority high
mtn list --tag work

# Show overdue tasks
mtn list --overdue

# Raw mdbase where expression
mtn list --where 'due < "2026-03-01" && priority == "urgent"'

# JSON output for scripting
mtn list --json

Show task detail

mtn show "Buy groceries"
mtn show tasks/Buy\ groceries.md

Tasks can be referenced by title or file path. Title matching tries exact match first, then substring.

Search

Full-text search across titles, body content, tags, contexts, and projects:

mtn search quarterly

Updating tasks

Complete a task

mtn complete "Buy groceries"

Sets status to done and records the completion date.

Update fields

mtn update "Write report" --status in-progress
mtn update "Write report" --priority urgent --due 2026-03-01
mtn update "Write report" --add-tag important --remove-tag draft
mtn update "Write report" --add-context office

Archive and delete

mtn archive "Write report"     # Adds "archive" tag
mtn delete "Old task"           # Checks for backlinks first
mtn delete "Old task" --force   # Skip backlink check

Time tracking

Track time spent on tasks via the timeEntries frontmatter field — the same format TaskNotes uses.

# Start a timer
mtn timer start "Write report"
mtn timer start "Write report" -d "Drafting introduction"

# Check active timers
mtn timer status

# Stop the running timer
mtn timer stop

# View time log
mtn timer log
mtn timer log --period today
mtn timer log --period week
mtn timer log --from 2026-02-01 --to 2026-02-28

Projects and statistics

Projects

# List all projects
mtn projects list
mtn projects list --stats    # With completion percentages

# Show tasks for a project
mtn projects show quarterly-review

Statistics

mtn stats

Shows total tasks, completion rate, overdue count, breakdown by status and priority, and total time tracked.

Interactive mode

Launch a REPL with live NLP preview that updates as you type:

mtn interactive
# or
mtn i

Type a task description and the preview line shows how it will be parsed (title, tags, dates, priority). Press Enter to create the task.

Configuration

Configuration is stored at ~/.config/mdbase-tasknotes/config.json.

mtn config --list                              # Show all settings
mtn config --set collectionPath=/path/to/vault  # Set collection path
mtn config --get collectionPath                 # Get a setting

Collection path resolution

The collection path is resolved in order:

1. --path / -p flag on any command
2. MDBASE_TASKNOTES_PATH environment variable
3. collectionPath in config file
4. Current working directory

Command reference

Command	Alias	Description
mtn init [path]		Initialize a new collection
mtn create <text...>		Create a task from natural language
mtn list [options]	ls	List tasks with filters
mtn show <task>		Show full task detail
mtn complete <task>	done	Mark task as completed
mtn update <task> [options]		Update task fields
mtn delete <task>	rm	Delete a task
mtn archive <task>		Add archive tag
mtn search <query>		Full-text search
mtn timer start <task>		Start time tracking
mtn timer stop		Stop running timer
mtn timer status		Show active timers
mtn timer log		Show time entry log
mtn projects list		List projects
mtn projects show <name>		Show project tasks
mtn stats		Show task statistics
mtn interactive	i	Interactive REPL
mtn config [options]		Manage configuration