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

> Learn to compare architecture diagrams with the Archify CLI. Generate validated receipts and visualize differences or export for programmatic use. Master diagram comparison today.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-02

---

**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:

```bash
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`:

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash

# 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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.