# How to Generate HTML Diagrams from JSON with Archify: Complete CLI Guide

> Generate interactive HTML diagrams from JSON using Archify CLI. Learn the simple `archify deliver` command for validation, rendering, and committing your diagrams.

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

---

**Use `archify deliver <type> <input.json> [output.html]` to validate, render, and atomically commit a self-contained interactive HTML diagram from any typed JSON specification.**

Archify is an open-source CLI tool that transforms structured JSON descriptions of systems into browser-ready HTML diagrams. According to the tt-a1i/archify source code, the tool supports architecture, workflow, sequence, data-flow, and lifecycle diagrams through a three-stage pipeline designed for safety and reproducibility.

## Understanding Archify's Three-Stage Pipeline

The rendering process in `archify/bin/archify.mjs` splits execution into distinct stages:

| Stage | Purpose | CLI Command |
|-------|---------|-------------|
| **Render** | Produce raw HTML without validation | `archify render <type> <input.json> [output.html]` |
| **Validate** | Run full validation with machine-readable output | `archify validate <type> <input.json> --json` |
| **Deliver** | Safe, atomic workflow with all checks | `archify deliver <type> <input.json> [output.html]` |

The **deliver** command is the recommended path for production use. It guarantees that generated HTML passes every deterministic check before replacing existing files.

## Installation and Setup

Install Archify globally for use across agent environments:

```bash
npx skills add tt-a1i/archify -g

```

The installer places the `archify` binary under `~/.agents/skills/archify` or your platform's equivalent agent skill directory.

## Preparing Your JSON Diagram

All diagram types share a common schema located in `archify/schemas/`. Here's a minimal web application architecture example, matching the shipped example at [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json):

```json
{
  "$schema": "https://raw.githubusercontent.com/tt-a1i/archify/main/archify/schemas/architecture.schema.json",
  "type": "architecture",
  "nodes": [
    { "id": "users", "type": "client", "label": "Users" },
    { "id": "cdn", "type": "cdn", "label": "CDN" },
    { "id": "lb", "type": "load-balancer", "label": "LB" },
    { "id": "api", "type": "service", "label": "API Server" },
    { "id": "db", "type": "database", "label": "Postgres" }
  ],
  "relationships": [
    { "source": "users", "target": "cdn", "label": "HTTPS" },
    { "source": "cdn", "target": "lb", "label": "Edge → LB" },
    { "source": "lb", "target": "api", "label": "Request" },
    { "source": "api", "target": "db", "label": "SQL" }
  ]
}

```

Save this as [`web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/web-app.architecture.json). The schema URL enables IDE autocompletion and validation.

## Generating HTML Diagrams: Core Commands

### Quick Render (Prototyping)

For rapid iteration without validation:

```bash
archify render architecture web-app.architecture.json web-app.html

```

This invokes `archify/renderers/architecture/render-architecture.mjs` directly and outputs raw HTML.

### Production Delivery (Recommended)

For validated, traceable artifacts:

```bash
archify deliver architecture web-app.architecture.json web-app.html --json --open

```

The **deliver** command executes five sequential operations:
1. **Freeze input** — creates read-only snapshot [`specification.snapshot.json`](https://github.com/tt-a1i/archify/blob/main/specification.snapshot.json) in staging
2. **Render** — runs the type-specific renderer
3. **Artifact check** — `scripts/check-render-output.mjs` validates schema, layout, and composition
4. **Atomic commit** — `renderers/shared/output-path.mjs` safely moves verified HTML to target
5. **Optional open** — launches browser when `--open` is passed

### Available Flags

| Flag | Values | Effect |
|------|--------|--------|
| `--quality` | `standard` \| `showcase` | `showcase` enables richer presets (signal-flow, blueprint themes) |
| `--repo-root <path>` | filesystem path | Enables source-evidence linking for "Evidence" badges |
| `--json` | boolean | Outputs diagnostic receipt as JSON |
| `--open` | boolean | Opens generated HTML in default browser |

## Understanding Generated HTML Structure

Archify produces self-contained files with three embedded data blocks:

```html
<script id="archify-data" type="application/json">…JSON source…</script>
<script id="archify-source-evidence-data" type="application/json">…repo evidence…</script>
<script id="archify-receipt-data" type="application/json">…validation receipt…</script>

```

These enable the viewer ([`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html)) to:
- Reload and re-render diagrams
- Execute guided story tours
- Trace routes between nodes
- Export PNG and Share-Card images

All functionality works without a server or build step.

## Advanced Workflows

### Live Preview with Auto-Reload

Start a development server that watches your JSON file:

```bash
archify preview architecture web-app.architecture.json

```

The server binds to `127.0.0.1` on a random port. Changes trigger re-rendering; validation failures preserve the last-good artifact while logging diagnostics.

### Delta Comparison

Generate side-by-side before/after diagrams:

```bash
archify compare architecture base.json head.json delta.html --json

```

This produces annotated HTML highlighting added nodes, removed edges, and moved components.

### Guided Scenario Generation

Request a pre-built diagram recipe:

```bash
archify guide "show a login flow" --json

```

Returns ready-made scenario specifications for common patterns.

### Batch Demo Rendering

Generate the bundled example quickly:

```bash
archify demo ./demo-output

```

Renders [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) to the specified directory.

## Production Delivery Example with Full Evidence

```bash
archify deliver architecture examples/moca-runtime.architecture.json \
    moca-runtime.html --quality showcase --repo-root $(pwd) --json --open

```

**Internal execution flow:**
- Source evidence injection pins the diagram to exact Git commit `9f1a1cf`
- Final receipt includes SHA-256 hashes for both specification and artifact
- Composition profile `signal-flow` confirms visual theme selection

**Sample JSON receipt output:**

```json
{
  "schemaVersion": 1,
  "ok": true,
  "command": "deliver",
  "type": "architecture",
  "input": "/home/user/moca-runtime.architecture.json",
  "output": "/home/user/moca-runtime.html",
  "specification": { "sha256": "a1b2c3…", "bytes": 1024 },
  "artifact": { "sha256": "d4e5f6…", "bytes": 45872 },
  "validation": {
    "checksPassed": 23,
    "checkCount": 23,
    "compositionProfile": "signal-flow",
    "compositionStatus": "ok"
  },
  "evidence": {
    "verified": true,
    "repository": "https://github.com/mco-org/mco",
    "revision": "9f1a1cf",
    "references": 14
  }
}

```

## Key Source Files Reference

| File | Role |
|------|------|
| `archify/bin/archify.mjs` | Main CLI dispatcher implementing all commands |
| `archify/renderers/<type>/render-*.mjs` | Per-type renderers (e.g., `render-architecture.mjs`) |
| `archify/scripts/check-render-output.mjs` | Final artifact validator run during delivery |
| `archify/renderers/shared/output-path.mjs` | Safe atomic file operations |
| `archify/schemas/*.schema.json` | JSON Schema contracts for each diagram type |
| [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) | Reference implementation and quick-start template |

## Summary

- **Install** Archify globally via `npx skills add tt-a1i/archify -g`
- **Author** JSON diagrams using schema-validated structures in `archify/schemas/`
- **Develop** with `archify preview` for live-reload feedback
- **Build** with `archify render` for quick checks or `archify deliver` for production safety
- **Verify** outputs contain embedded provenance data for reproducibility
- **Extend** using `archify compare` and `archify guide` for team workflows

## Frequently Asked Questions

### What diagram types does Archify support?

Archify supports **architecture**, **workflow**, **sequence**, **data-flow**, and **lifecycle** diagrams. Each type has a dedicated renderer under `archify/renderers/` and matching JSON Schema in `archify/schemas/`.

### Why should I use `deliver` instead of `render`?

The **deliver** command guarantees safety through input freezing, validation, artifact checking, and atomic file replacement. **Render** skips all checks and overwrites output directly—use it only for rapid prototyping.

### How do I enable source code linking in diagrams?

Pass `--repo-root $(pwd)` to the deliver command. This triggers `render-architecture.mjs` to inject `<script id="archify-source-evidence-data">` containing the exact Git commit, enabling the "Evidence" badge in the rendered HTML.

### Can I use Archify without installing it permanently?

Yes. The `npx skills add` command handles one-time installation. For ephemeral usage, inspect `archify/bin/archify.mjs` to run the Node.js script directly with `node --experimental-vm-modules` if dependencies are pre-installed.