# mdt_cli
> the CLI for mdt (manage markdown templates)
<br />
[![Crate][crate-image]][crate-link] [![Docs][docs-image]][docs-link] [![Status][ci-status-image]][ci-status-link] [![Coverage][coverage-image]][coverage-link] [![Unlicense][unlicense-image]][unlicense-link]
<br />
<!-- {=mdtPackageDocumentation} -->
`mdt` helps library and tool maintainers keep README sections, source-doc comments, and docs-site content synchronized across a project. Define content once with comment-based template tags, then reuse it across markdown files, code documentation comments, READMEs, mdbook docs, and more so your docs do not drift.
<!-- {/mdtPackageDocumentation} -->
## Installation
<!-- {=mdtCliInstall} -->
- Install with npm:
```sh
npm install -g @m-d-t/cli
```
- Or run it without installing:
```sh
npx @m-d-t/cli --help
```
- Or download a prebuilt binary from the [latest GitHub release](https://github.com/ifiokjr/mdt/releases/latest)
- Or install with Cargo:
```sh
cargo install mdt_cli
```
<!-- {/mdtCliInstall} -->
<!-- {=mdtCliUsage} -->
### CLI Commands
- `mdt init [--path <dir>]` — Create a sample `.templates/template.t.md` file and starter `mdt.toml`.
- `mdt check [--path <dir>] [--verbose]` — Verify all target blocks are up-to-date. Exits non-zero if any are stale.
- `mdt update [--path <dir>] [--verbose] [--dry-run]` — Update all target blocks with latest source content.
- `mdt info [--path <dir>]` — Print project diagnostics and cache observability metrics.
- `mdt doctor [--path <dir>] [--format text|json]` — Run health checks with actionable hints, including cache validity and efficiency.
- `mdt assist <assistant> [--format text|json]` — Print an official assistant setup profile with MCP config and repo-local guidance.
- `mdt lsp` — Start the mdt language server (LSP) for editor integration. Communicates over stdin/stdout.
- `mdt mcp` — Start the mdt MCP server for AI assistants. Communicates over stdin/stdout.
### Diagnostics Workflow
- Run `mdt info` first to inspect project shape, diagnostics totals, and cache reuse telemetry.
- Run `mdt doctor` when you need actionable health checks and remediation hints (config/data/layout/cache).
- Use `MDT_CACHE_VERIFY_HASH=1` when troubleshooting cache consistency issues and comparing reuse behavior.
<!-- {/mdtCliUsage} -->
<!-- {=mdtTemplateSyntax} -->
### Template Syntax
**Source tag** (defines a template block in `*.t.md` definition files):
```markdown
<!-- {@blockName} -->
Content to inject
<!-- {/blockName} -->
```
**Target tag** (marks where content should be injected):
```markdown
<!-- {=blockName} -->
This content gets replaced
<!-- {/blockName} -->
```
**Inline tag** (source-free interpolation using configured data):
```markdown
Current version: <!-- {~version:"{{ package.version }}"} -->0.0.0<!-- {/version} -->
```
```markdown
| Artifact | Version |
| -------- | ------------------------------------------------------------------------- |
| mdt_cli | <!-- {~cliVersion:"{{ package.version }}"} -->0.0.0<!-- {/cliVersion} --> |
```
**Filters and pipes:** Template values support pipe-delimited transformers:
```markdown
<!-- {=block|prefix:"\n"|indent:" "} -->
```
Available transformers: `trim`, `trimStart`, `trimEnd`, `indent`, `prefix`, `suffix`, `linePrefix`, `lineSuffix`, `wrap`, `codeBlock`, `code`, `replace`, `if`.
<!-- {/mdtTemplateSyntax} -->
<!-- {=mdtBadgeLinks:"mdt_cli"} -->
[crate-image]: https://img.shields.io/crates/v/mdt_cli.svg [crate-link]: https://crates.io/crates/mdt_cli [docs-image]: https://docs.rs/mdt_cli/badge.svg [docs-link]: https://docs.rs/mdt_cli/ [ci-status-image]: https://github.com/ifiokjr/mdt/workflows/ci/badge.svg [ci-status-link]: https://github.com/ifiokjr/mdt/actions?query=workflow:ci [coverage-image]: https://codecov.io/gh/ifiokjr/mdt/branch/main/graph/badge.svg [coverage-link]: https://codecov.io/gh/ifiokjr/mdt [unlicense-image]: https://img.shields.io/badge/license-Unlicence-blue.svg [unlicense-link]: https://opensource.org/license/unlicense
<!-- {/mdtBadgeLinks} -->