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

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.

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

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.

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

According to the 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.

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.

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, 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.

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