metrics.md

command	metrics
summary	Get, list, and rank shared Markdown metrics (file length, token estimate, readability, …).

mdsmith metrics

Metrics are the shared measurements rules compute: file length, section length, token estimate, readability scores. This CLI surfaces them as a standalone tool for triage.

mdsmith metrics <command> [flags] [files...]

Subcommands

Subcommand	Description
get	Emit all metrics for a single file
list	List available metrics in the registry
rank	Rank files by selected metrics

metrics get

Emit every registered metric for a single Markdown file as a data object. The shape is a flat map with path plus one key per metric. To narrow to one field, pipe through jq or yq.

mdsmith metrics get [flags] <file>

Flag	Default	Description
-f, --format	text	text, json, or yaml

mdsmith metrics get docs/guides/install.md
mdsmith metrics get -f json README.md
mdsmith metrics get -f yaml README.md | yq .readability
mdsmith metrics get -f json README.md | jq .avg-words-per-sentence

metrics list

mdsmith metrics list [flags]

Flag	Default	Description
-f, --format	text	text, json, or yaml
--scope	file	Metric scope (only file)

metrics rank

mdsmith metrics rank [flags] [files...]

Flag	Default	Description
-c, --config	auto	Override config path
-f, --format	text	text, json, or yaml
--metrics	—	Comma-separated metric IDs to compute
--by	—	Metric ID to rank by
--order	desc	asc or desc
--top	0	Limit output to N rows (0 = all)
--no-gitignore	false	Skip gitignore filtering
--follow-symlinks	config	Follow symlinks; tri-state
--max-input-size	2MB	Max file size (e.g. 2MB, 0=none)

metrics rank counts only authored bytes. Content between <?include?> and <?catalog?> markers is excluded. Embedded content is measured against its source file, not the host that pulls it in.

With no file arguments, defaults to the current directory.

Available metrics

Three metrics are off by default in rank: readability (MET008), sentences (MET009), and avg-words-per-sentence (MET010). They appear in get and list unconditionally.

Metric	Default	Description
bytes	yes	Raw file byte count
lines	yes	Total line count
words	yes	Word count from plain text
headings	yes	Number of headings
token-estimate	yes	Token estimate (0.75 × words)
conciseness	yes	Heuristic conciseness score (0–100)
readability	no	Automated Readability Index (ARI grade level)
sentences	no	Sentence count from plain text
avg-words-per-sentence	no	Average words per sentence

Examples

mdsmith metrics list
mdsmith metrics get -f json README.md
mdsmith metrics get -f yaml docs/guides/install.md
mdsmith metrics rank --by bytes --top 10 .
mdsmith metrics rank --by token-estimate --top 5 docs/
mdsmith metrics rank --metrics bytes,sentences --by sentences plan/
mdsmith metrics rank --metrics readability --by readability --top 20 docs/

Exit codes

Code	Meaning
0	Output produced
2	Runtime / config error