30-second answer

diff compares two assessments and reports what changed. Its help text carries the qualifier that matters: what changed, and what it does not say.

PowerShell
m365-governance diff [-h] [--format {markdown,json}]
                     [--fail-on-regression]
                     before after

Both arguments are assessments, from assess.

The distinction the comparison has to make

A rule that read pass in March and fail in August has two possible explanations, and they call for opposite responses:

  • the tenant changed. Somebody turned something on. That is a finding.
  • the rule changed. A new engine version tightened what the rule establishes. The tenant may be untouched.

A comparison that reported only the outcomes would present the second as if it were the first, and a team would go looking for a change nobody made. The comparison keeps them apart.

Options

--format is markdown or json. Note there is no html here, unlike evaluate and report.

--fail-on-regression exits non-zero when any rule left pass. That is the setting for a pipeline that treats losing a pass as a build failure.

Exit codes

0 compared. 1 a rule left pass and --fail-on-regression was given. 2 one of the documents was not an assessment.