How to Use the Archify CLI to Compare Architecture Diagrams: A Complete Guide

The Archify CLI provides a compare command that generates a validated receipt showing differences between two architecture diagrams, which you can then render as a visual diff in the browser or export for programmatic use.

Comparing architecture diagrams is essential for tracking system evolution, reviewing changes in pull requests, and communicating deltas to stakeholders. The tt-a1i/archify repository implements this through a structured compare receipt system that records operations, validates results, and powers interactive viewers. This guide explains the complete workflow using actual source code from the project.

Running the Archify CLI Compare Command

The archify compare command accepts two diagram sources—either file paths or inline JSON—and produces a compare receipt containing the diff data. The receipt follows a strict schema that downstream tools consume for validation and rendering.

Basic syntax:

archify compare <source-a> <source-b> [options]

The CLI supports multiple input formats including .json architecture definitions and .archify files. By default, output goes to stdout, but you can persist the receipt with --output.

Validating the Compare Receipt

After generation, Archify automatically validates the receipt against three criteria implemented in scripts/package-smoke.mjs:

• command === 'compare' — confirms the correct operation type
• completeness === 'complete' — ensures full processing
• validation.checksPassed === validation.checkCount — verifies all quality checks passed

This validation logic appears at lines 286-294 of scripts/package-smoke.mjs:

// From scripts/package-smoke.mjs — receipt validation for compare operations
if (receipt.command !== 'compare') throw new Error('Wrong command');
if (receipt.completeness !== 'complete') throw new Error('Incomplete');
if (receipt.validation.checksPassed !== receipt.validation.checkCount) {
  throw new Error('Checks failed');
}

You can manually trigger validation with archify verify receipt.json or rely on the CLI's automatic verification before rendering.

Viewing Diagram Differences in the Browser

The visual diff renders through an HTML viewer that consumes the compare receipt. The example file examples/checkout-platform-delta.html demonstrates this integration: it embeds a <script id="archify-compare-receipt"> element containing the receipt JSON, which the viewer component parses to display side-by-side comparisons.

From lines 34715-35039 of examples/checkout-platform-delta.html, the viewer:

1. Extracts receipt data from the embedded script tag
2. Identifies semantic kinds (e.g., frontend, backend, database)
3. Renders two selected kinds side-by-side with color-coded changes

Added relationships appear in green, removed in red, and modified connections show before/after states. The viewer supports interactive filtering so you can focus on specific architectural layers.

Complete Workflow Examples

Basic File-to-File Comparison

Compare two saved diagrams and open the result:

# Generate receipt

archify compare samples/diagram-old.json samples/diagram-new.json \
    --output /tmp/compare-receipt.json

# Launch browser viewer

archify view /tmp/compare-receipt.json

Piped Quick Comparison

For rapid iteration, pipe directly from compare to view:

archify compare a.json b.json | archify view

This skips the intermediate file and streams the receipt through the viewer.

Restricting to Specific Semantic Kinds

Limit the diff to relevant architectural layers:

archify compare old.json new.json \
    --kind frontend backend \
    --output delta.html

The resulting viewer only shows relationships where both endpoints match the specified kinds—ideal for large systems where full diagrams become unwieldy.

CI Pipeline Integration

Fail builds when architectural changes violate constraints:

archify compare baseline.json proposed.json --output receipt.json

if ! archify verify receipt.json; then
    echo "❌ Architecture comparison failed validation"
    exit 1
fi

# Optional: save HTML report for human review

archify view receipt.json --format html --output report.html

The --no-color flag ensures clean logs in CI environments.

Key Command Options

Option	Purpose
--output <path>	Write receipt to file instead of stdout
--kind <kind> [<kind>]	Filter to one or two semantic kinds
--format json|html	Choose receipt format; HTML includes embedded viewer
--no-color	Disable ANSI colors for CI compatibility

Understanding the Compare Receipt Schema

The receipt produced by archify compare serves as the single source of truth for all downstream operations. A valid receipt contains:

• command: Always "compare"
• completeness: "complete" when successful
• validation: Object with checksPassed and checkCount
• diff: The actual diagram delta data

The sample receipt at examples/checkout-platform-delta.receipt.json demonstrates this structure as generated by real compare operations. Tools like package-smoke.mjs rely on this schema to guarantee that comparison results are reproducible and verifiable.

Summary

• Use archify compare to generate diff receipts from two diagram sources—files, stdin, or mixed inputs
• Validation happens automatically via criteria defined in scripts/package-smoke.mjs: correct command type, complete status, and passed checks
• Visual rendering consumes receipts through HTML viewers like examples/checkout-platform-delta.html, which parse embedded receipt scripts at runtime
• Semantic kind filtering narrows large architecture diffs to relevant subsystems
• CI integration combines archify compare, archify verify, and exit-code checking for automated quality gates

Frequently Asked Questions

What file formats does the Archify CLI compare command accept?

The archify compare command accepts JSON architecture definitions and .archify files as primary inputs. Both positional arguments can be file paths, or you can pipe JSON content via stdin using the - placeholder. The output format—JSON for programmatic use or HTML for embedded viewing—is controlled by the --format flag.

How is a compare receipt validated in Archify CLI?

Validation occurs through three assertions implemented in scripts/package-smoke.mjs at lines 286-294: the receipt's command field must equal "compare", the completeness field must be "complete", and the validation object must show all checks passed. These criteria ensure the comparison operation finished successfully before any viewer renders results.

Can I view diagram differences without saving a receipt file?

Yes. Pipe the compare output directly to the viewer: archify compare a.json b.json | archify view. This streams the receipt through stdin without intermediate files. For browser-based viewing, use --format html and redirect to a temporary path, or rely on the viewer's automatic tempfile handling.

What are semantic kinds in Archify diagram comparison?

Semantic kinds are architectural categories like frontend, backend, database, or queue that classify diagram nodes. The --kind option restricts comparisons to relationships involving your specified kinds, reducing noise in large system diagrams. The viewer renders two selected kinds side-by-side, ignoring unrelated connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}