CLI commands

npx dowse <command> [options]

Common options

Available on most commands.

Option	Default	Description
--since <date>	12 months ago	Start of the git window. Anything git can parse.
--until <date>	—	End of the git window
--complexity <type>	loc	Complexity proxy: loc | cyclomatic | cognitive
--json	false	Write JSON to stdout

---

analyze

Analyses the workspace, writes .dowse/dowse.json, and prints a summary.

dowse analyze [dir]

Option	Default	Description
--top <n>	10	Number of hotspots to display
--out <path>	.dowse/dowse.json	Output path
--verify-churn [n]	off	Verify change frequency of the top N files (default 20) by AST
--min-degree <n>	0.3	Minimum coupling degree (percentages like 30 also accepted)
--min-shared <n>	5	Minimum shared commits for coupling

With --json the report goes to stdout and no file is written.

---

hotspots

Prints just the hotspot ranking.

dowse hotspots [dir] --top 15

---

coupling

Shows change coupling.

dowse coupling [dir] --hidden

Option	Default	Description
--hidden	false	Only hidden coupling (co-change with no dependency)
--files	false	Also show file-level coupling
--top <n>	20	Number of rows
--min-degree <n>	0.3	Minimum degree
--min-shared <n>	5	Minimum shared commits

Lower the threshold to catch what you are missing

Two very active packages have a large denominator, which drags the degree down. --min-degree 15 often surfaces real pairs.

---

why

Explains why two things change together.

dowse why <a> <b>

Each target can be a package name, a file path, or a directory — resolved in that order (package name → exact path → prefix match).

Option	Default	Description
--cwd <path>	.	Directory to analyse
--top <n>	10	Number of file pairs to show
--commits <n>	10	Number of representative commits

dowse why @acme/admin-web @acme/doctor-web
dowse why packages/ui src/api --since "6 months ago"

---

health

Shows Code Health and the smell breakdown.

dowse health [dir]
dowse health --file src/foo.ts    # deductions for one file

Option	Default	Description
--file <path>	—	Show the breakdown for one file only
--top <n>	10	Number of rows

---

knowledge

Shows ownership and bus factor.

dowse knowledge [dir] --top 15

Reports bus factor per package, the contributor list, and an off-boarding simulation showing what would be left unowned if the main developer left.

---

report

Generates a self-contained single-file HTML report. It makes no external requests and the data is embedded, so you can share the file as-is.

dowse report [dir] --out report.html

---

diagnose

Diagnoses top hotspots with an LLM (requires Claude Code).

dowse diagnose [dir] --top 3

Option	Default	Description
--top <n>	3	How many to diagnose (cost scales with this)
--model <model>	—	Model to use

An opinion, not a measurement

Keep it separate from the deterministic metrics.

---

fix

Has an agent fix a hotspot, verifies the result, and measures the complexity delta (requires Claude Code).

dowse fix [target]
dowse fix src/foo.ts --apply

Option	Default	Description
--apply	false	Keep verified changes on a working branch
--cwd <path>	.	Directory to analyse
--top <n>	1	How many targets when none is named
--max-diff-lines <n>	400	Maximum accepted diff size
--skip-diagnosis	false	Skip diagnosis and go straight to fixing
--skip-verification	false	Skip type check and tests (not recommended)
--typecheck-command <script>	inferred	package.json script name for the type check
--test-command <script>	inferred	package.json script name for tests

It is a dry run by default. See Closing the loop for the safety valves.

---

check

Quality gate. Exits 1 on violation.

dowse check [dir] --min-file-health 3

Option	Description
--min-file-health <n>	Floor for file health
--min-package-health <n>	Floor for package health
--max-hotspot <n>	Ceiling for hotspot score (0–1)
--min-bus-factor <n>	Floor for package bus factor
--max-hidden-coupling <n>	Ceiling on hidden coupling count
--sarif <path>	Emit SARIF for GitHub Code Scanning

It checks nothing by default

Only thresholds you name explicitly are enforced. Measure where you are first, then start from a level you can actually pass.

---

diff

Assesses whether changes since a base touched risky ground.

dowse diff <base>
dowse diff origin/main --markdown

Option	Default	Description
--head <ref>	HEAD	Comparison target
--cwd <path>	.	Directory to analyse
--markdown	false	Write PR-comment Markdown to stdout
--out <path>	—	Write the Markdown to a file

---

mcp

Starts the MCP server over stdio.

dowse mcp [dir] --since "6 months ago"

See Coding agents and the MCP reference.