diff

Compare audit results against a baseline to identify new issues, resolved issues, and score changes over time

Compare audit results against a baseline to find new and resolved issues.

Synopsis

vertaa diff [job-id] [options]

Description

The diff command compares audit results against a baseline to show what changed. Use it to:

Identify new issues introduced since the last baseline
Track resolved issues
Generate diff data for release notes or PR comments

Quick Examples

Compare a job against the default baseline

$vertaa diff <job-id>

Compare two local JSON files

$vertaa diff --from-file current.json --baseline .vertaaux/baseline.json

Compare two audit jobs directly

$vertaa diff --compare <other-job-id> <job-id>

Options

Parameter	Type	Required	Description
--baseline	`string`	optional	Path to baseline file for comparisonDefault: `.vertaaux/baseline.json`
--compare	`string`	optional	Compare two audit jobs directly instead of using a baseline file
--from-file	`string`	optional	Read current audit results from a local JSON file instead of fetching from the API
--format	`string`	optional	Output format: human, jsonDefault: `human`
--verbose	`boolean`	optional	Show all present issues, not just new and resolvedDefault: `false`

Comparison Modes

Against Baseline File

Compare an audit job against a saved baseline:

Compare against default baseline (.vertaaux/baseline.json)

$vertaa diff <job-id>

Compare against a specific baseline file

$vertaa diff <job-id> --baseline custom-baseline.json

Two Audit Jobs

Compare two audit jobs directly (no baseline file needed):

Compare two jobs from the API

$vertaa diff --compare <baseline-job-id> <current-job-id>

From Local Files

Compare using local JSON files without API calls:

Compare two local JSON files

$vertaa diff --from-file latest-audit.json --baseline .vertaaux/baseline.json

Output Format

Human Readable (Default)

VertaaUX Diff Report
══════════════════════════════════════════════════════════

Score Changes
────────────────────────────────────────────────────────
Overall:       78 → 85  (+7)  ▲
UX:            82 → 88  (+6)  ▲
Accessibility: 71 → 79  (+8)  ▲
Info Arch:     80 → 85  (+5)  ▲
Performance:   79 → 80  (+1)  ▲

Issues Summary
────────────────────────────────────────────────────────
New Issues:      2
Resolved Issues: 9
Unchanged:       6

New Issues (2)
────────────────────────────────────────────────────────
[ERROR] Missing form label
        at input#email
        Rule: form-label-required

[WARN]  Image exceeds viewport on mobile
        at img.hero-banner
        Rule: responsive-images

Resolved Issues (9)
────────────────────────────────────────────────────────
[ERROR] Missing alt text on hero image ✓
[ERROR] Color contrast ratio below minimum ✓
[WARN]  No skip link for keyboard navigation ✓
... (6 more)

JSON Format

{
  "comparison": {
    "baseline": ".vertaaux/baseline.json",
    "current": "job_abc123",
    "timestamp": "2026-01-15T10:30:00Z"
  },
  "scores": {
    "before": { "overall": 78, "ux": 82, "accessibility": 71 },
    "after": { "overall": 85, "ux": 88, "accessibility": 79 },
    "delta": { "overall": 7, "ux": 6, "accessibility": 8 }
  },
  "issues": {
    "new": [
      {
        "fingerprint": "x1y2z3",
        "rule": "form-label-required",
        "severity": "error",
        "message": "Missing form label"
      }
    ],
    "resolved": [
      {
        "fingerprint": "a1b2c3",
        "rule": "alt-text-required",
        "severity": "error",
        "message": "Missing alt text on hero image"
      }
    ],
    "unchanged": []
  },
  "summary": {
    "new_count": 2,
    "resolved_count": 9,
    "unchanged_count": 6,
    "improved": true
  }
}

Exit Codes

Code	Meaning
`0`	No new issues found
`1`	New issues detected
`2`	Error during comparison (file not found, network failure)

Common Workflows

CI Baseline Gating

Fail the build if new issues are introduced:

# Run audit and diff against baseline
vertaa audit https://example.com --format json --output audit.json
vertaa diff --from-file audit.json --baseline .vertaaux/baseline.json

Piping to Release Notes

Generate release notes from a diff:

vertaa diff <job-id> --format json | vertaa release-notes --format markdown

Verbose Output

See all issues (including unchanged) for a complete picture:

vertaa diff <job-id> --verbose

URL Comparison

To compare two live URLs or two audit JSON files with LLM-powered narrative analysis, use the compare command instead.

baseline

Create baselines for comparison

audit

Run audits with baseline comparison

CI/CD Integration

Automate diff reports in pipelines

Was this page helpful?

baseline

audit

CI/CD Integration

On this page