# How to Generate an Architecture Diagram with Archify: CLI Workflow Guide

> Generate architecture diagrams easily with Archify CLI. Convert code or text to interactive diagrams in four simple steps. Get your architecture visualization today!

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

---

**Archify converts natural-language descriptions or repository source code into polished, interactive architecture diagrams through a four-step CLI workflow involving generation, validation, preview, and delivery.**

Archify is an open-source skill that transforms text prompts into typed JSON intermediate representations (IR) and renders them as interactive HTML, SVG, or PNG artifacts. Whether you are documenting microservice dependencies or visualizing API data flows, the tool provides a deterministic pipeline for generating professional architecture diagrams directly from your terminal.

## Installing Archify

You can install Archify globally for AI agents (Cursor, Claude Code, Codex, Opencode) or locally via ZIP file. Global installation makes the `archify` command available across projects.

```bash

# Global installation (recommended for agent workflows)

npx skills add tt-a1i/archify -g

```

For local usage, extract the ZIP and navigate to the repository root where the `archify/` folder lives. All subsequent commands assume this directory structure.

## The Four-Step Workflow to Generate an Architecture Diagram

Archify implements a strict pipeline in `archify/bin/archify.mjs` that ensures diagram integrity through atomic validation. The process consists of **generate**, **validate**, **preview**, and **deliver** phases.

### Step 1: Generate the Typed JSON IR

Use the `guide` command to convert a natural-language description into a typed JSON IR. This intermediate representation guarantees reproducible, deterministic builds.

```bash
node archify/bin/archify.mjs guide "Browser -> API -> Redis cache -> PostgreSQL fallback" --json

```

The command outputs a JSON file containing the architecture schema. You can refine this iteratively by running additional `guide` commands with follow-up prompts such as "add load balancer in front of API" or "highlight the rollback path." Archify preserves the original typed JSON source while applying incremental updates.

### Step 2: Validate Schema and Logic

Before rendering, run the `validate` command to check the JSON for schema compliance, layout constraints, and logical consistency. This fails fast if any rule is broken, preventing broken diagrams from being published.

```bash
node archify/bin/archify.mjs validate architecture examples/web-app.architecture.json --quality showcase --json

```

According to the [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) contract, validators enforce structural integrity of the diagram components and their relationships.

### Step 3: Preview Locally (Optional)

The `preview` command starts a lightweight desktop loop that watches the JSON file and displays a live preview. The view only updates when validation passes, ensuring you never review a broken diagram.

```bash
node archify/bin/archify.mjs preview architecture examples/web-app.architecture.json /tmp/web-app.html --quality showcase

```

This watch-mode is particularly useful when iteratively refining complex architectures with multiple stakeholders.

### Step 4: Deliver the Final Artifact

Use the `deliver` command to write the final HTML, SVG, or PNG artifact atomically. The `--open` flag automatically launches the diagram in your default browser.

```bash
node archify/bin/archify.mjs deliver architecture examples/web-app.architecture.json /tmp/web-app.html --quality showcase --open --json

```

The generated file includes an interactive viewer where you can search nodes, trace upstream/downstream reach, and compare semantic roles without manually editing topology.

## Export Formats and Share Cards

Once delivered, you can export the architecture diagram in multiple formats via the **Export** menu inside the viewer:

- **PNG** and **SVG** for static documentation
- **WebM** for animated presentations
- **Share-card images** (1200 × 630 pixels) ideal for README badges or release notes

Share cards embed the full diagram context, making them perfect for social sharing or repository documentation.

## Summary

- **Install** Archify globally via `npx skills add` or locally from the ZIP file to begin generating architecture diagrams.
- **Generate** typed JSON IR using the `guide` command with natural-language prompts describing your system components and data flow.
- **Validate** schemas with the `validate` command to enforce layout and logical consistency before delivery.
- **Preview** changes in real-time using the `preview` command, which only updates the view on passing validation.
- **Deliver** final artifacts in HTML, PNG, or SVG formats using the `deliver` command with optional `--open` flag for immediate review.
- **Export** shareable assets including 1200 × 630 share cards for documentation and social sharing.

## Frequently Asked Questions

### What is the typed JSON IR in Archify?

The typed JSON IR (Intermediate Representation) is a deterministic schema that Archify generates from your natural-language prompts. Stored in files like [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json), this format guarantees that diagrams can be reproduced identically across different environments and allows for programmatic validation before rendering.

### How do I validate an architecture diagram before exporting?

Run `node archify/bin/archify.mjs validate architecture path/to/diagram.json --quality showcase --json` to check for schema violations, layout errors, and logical inconsistencies. The validation step is atomic, meaning it prevents broken diagrams from proceeding to the preview or delivery stages.

### Can I preview my architecture diagram while editing?

Yes. Use the `preview` command to start a watch-mode session that monitors your JSON file for changes. The live preview only updates when the file passes validation, ensuring you always see a valid representation of your architecture while you iterate on the design.

### What export formats does Archify support?

Archify supports PNG, SVG, and WebM exports through the viewer's Export menu. Additionally, you can generate 1200 × 630 pixel share cards that embed the full diagram context, making them suitable for GitHub README files, release notes, or social media sharing.