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 exists), 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 diff when --diff is set.
• json — Machine-readable JSON. Includes ok, stale, and stale_files so automation can distinguish 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. This first slice focuses on practical presets: mdt prints MCP configuration snippets and repo-local guidance rather than introducing 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 command 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. 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. Communicates over stdin/stdout using the Model Context Protocol.

mdt mcp

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

Environment variables