CLI Reference

Global options

mdt [OPTIONS] [COMMAND]

Commands

mdt init

Create a sample .templates/template.t.md file with a getting-started example.

mdt init
mdt init --path ./my-project

If .templates/template.t.md exists (or legacy template.t.md/templates/template.t.md), it prints a message and exits without overwriting.

Creates a file containing:

<!-- {@greeting} -->

Hello from mdt! This is a source block.

<!-- {/greeting} -->

mdt check

Verify that all target blocks are up to date. Exits with code 1 if any are stale.

mdt check
mdt check --diff
mdt check --format json
mdt check --format github

Exit codes:

Output formats:

• text — Human-readable output. Lists stale blocks with file paths, colored headings, and colored diagnostics when the terminal supports color. Includes the diff when --diff is set.
• json — Machine-readable JSON. Includes ok, stale, and stale_files so automation can tell block drift from formatter-only file drift.
• github — GitHub Actions ::warning annotations. Produces inline warnings on PR diffs.

JSON payload

mdt check --format json returns:

• ok — overall success boolean
• stale — block-level drift entries with file and block
• stale_files — formatter-only file drift entries with file

When formatter-aware normalization would change the full file without changing any managed block body, stale_files is populated and stale can remain empty.

Clean output:

{ "ok": true, "stale": [], "stale_files": [] }

Formatter-only drift example:

{
	"ok": false,
	"stale": [],
	"stale_files": [{ "file": "docs/readme.md" }]
}

mdt update

Update all target blocks with the latest source content.

mdt update
mdt update --dry-run
mdt update --watch

In normal mode, prints the number of blocks and files updated:

Updated 3 block(s) in 2 file(s).

If everything is already in sync:

All target blocks are already up to date.

Dry run shows what would change without modifying files:

Dry run: would update 3 block(s) in 2 file(s):
  readme.md
  src/lib.rs

Watch mode keeps running after the initial update, watching for file changes with 200ms debouncing:

Updated 3 block(s) in 2 file(s).

Watching for file changes... (press Ctrl+C to stop)

File change detected, updating...
All target blocks are already up to date.

Watch mode is not available with --dry-run.

mdt list

Display all provider and target blocks in the project.

mdt list

Output:

Sources:
  @installGuide .templates/template.t.md (2 target(s))
  @apiDocs .templates/template.t.md (3 target(s))

Targets:
  =installGuide readme.md [linked]
  =installGuide crates/my-lib/readme.md [linked]
  =apiDocs readme.md [linked]
  =apiDocs src/lib.rs |trim|indent [linked]
  ~version readme.md [inline]
  =orphanBlock docs/old.md [orphan]

2 source(s), 6 target(s)

Status indicators:

Transformers are shown after the file path when present.

mdt info

Print a human-readable diagnostics summary for the current project.

mdt info
mdt info --path ./my-project
mdt info --format json

Includes:

• Project root and resolved config path (mdt.toml, .mdt.toml, or .config/mdt.toml; or none).
• Provider/consumer counts, orphan targets, and unused sources.
• Data namespaces and their configured source files.
• Template file count, discovered template files, and template directory hints.
• Diagnostic totals (errors/warnings) and missing source names.
• Cache observability details (artifact path/health, schema compatibility, hash verification mode, cumulative reuse/reparse totals, and last scan metrics).

mdt doctor

Run project health checks with remediation hints and an explicit pass/warn/fail summary.

mdt doctor
mdt doctor --path ./my-project
mdt doctor --format json

Checks include:

• Config discovery and config parse status.
• Data source loading and parse validity.
• Template layout conventions (.templates/ preferred).
• Provider/consumer integrity (duplicates, missing sources, orphan targets, unused sources).
• Parser diagnostics aggregation.
• Cache artifact validity and schema compatibility.
• Cache hash verification mode guidance.
• Cache efficiency trend analysis based on reuse vs reparse telemetry.

Text output prints one line per check with a status tag (PASS, WARN, FAIL, SKIP) and optional hints. JSON output includes ok, summary, and a detailed checks array.

mdt assist

Print an official assistant setup profile. The first slice focuses on practical presets: MCP configuration snippets and repo-local guidance, not a plugin marketplace.

mdt assist claude
mdt assist cursor
mdt assist pi --format json

Supported assistants:

• generic
• claude
• cursor
• copilot
• pi

text output includes:

• a ready-to-copy MCP config snippet
• suggested repo-local guidance for your assistant instructions
• assistant-specific notes for the chosen profile

json output returns the same setup information in a machine-readable shape, including mcp_config, repo_guidance, and notes.

Use this when you want a quick, official starting point for wiring mdt mcp into an assistant workflow.

mdt lsp

Start the language server for editor integration. It communicates over stdin/stdout using the Language Server Protocol.

mdt lsp

The LSP provides:

• Diagnostics — Warnings for stale targets, missing sources, and source blocks in non-template files.
• Completions — Source name suggestions inside target tags. Transformer name suggestions after |.
• Hover — Shows source content when hovering over target tags. Shows consumer count when hovering over source tags.
• Go to definition — Jump from a target tag to its source definition.
• Document symbols — Lists all blocks in the current file.
• Code actions — Quick-fix to update a stale target block in place.

mdt mcp

Start the MCP server for AI integrations. It communicates over stdin/stdout using the Model Context Protocol.

mdt mcp

Use this when you want an AI assistant to query template sources, targets, and render context directly from your project.

Environment variables