How to Use Archify to Render Diagrams Directly: A Complete CLI Guide

You can render interactive system diagrams directly from JSON using Archify's CLI by validating your schema with archify.mjs validate and generating HTML with archify.mjs deliver, producing deterministic, self-contained SVG visualizations with built-in viewer controls.

Archify is an open-source tool that transforms plain-English system descriptions into interactive, exportable diagrams. According to the tt-a1i/archify source code, the workflow centers on a typed JSON intermediate representation (IR), strict schema validation, and deterministic rendering into standalone HTML files. This guide walks you through the exact commands and file structures needed to use Archify to render diagrams directly from your terminal.

Installing the Archify CLI

Before rendering, you must install the skill to add Archify's binaries and renderers to your environment. The recommended approach uses npx for global availability:

npx skills add tt-a1i/archify -g

This command installs the CLI entry point at archify/bin/archify.mjs along with all renderer modules and JSON schemas.

Creating the JSON Intermediate Representation

Archify consumes a strict JSON IR that describes diagram components, relationships, and visual styling. The schema definitions live in archify/schemas/ and enforce type safety for fields like nodes, edges, and meta configurations.

A minimal architecture diagram requires three top-level keys:

• meta: Controls animation, locale, and visual presets
• nodes: Array of components with id, kind, and label
• edges: Array of connections with from and to references

{
  "meta": {
    "locale": "en",
    "animation": "trace",
    "visual_preset": "signal-flow"
  },
  "nodes": [
    { "id": "browser", "kind": "frontend", "label": "Browser" },
    { "id": "api", "kind": "backend", "label": "API Server" },
    { "id": "db", "kind": "database", "label": "PostgreSQL" }
  ],
  "edges": [
    { "from": "browser", "to": "api" },
    { "from": "api", "to": "db" }
  ]
}

Supported diagram types include architecture, workflow, sequence, dataflow, and lifecycle, each with dedicated renderers under archify/renderers/<type>/render-<type>.mjs.

Validating Your Diagram Schema

Validation ensures your JSON conforms to layout rules and routing constraints before rendering. Run archify/bin/archify.mjs with the validate subcommand, specifying the diagram type, input file, and quality tier:

node archify/bin/archify.mjs validate architecture my-diagram.json --quality showcase --json

The --quality showcase flag enforces strict layout rules suitable for presentations. Validation failures return a JSON receipt with exact fix suggestions, while successful validation exits silently (or outputs structured JSON when using --json).

Rendering to HTML

After validation, use the deliver subcommand to generate the final HTML file. This command merges the validated JSON with the viewer template at archify/templates/viewer.html and injects deterministic SVG markup generated by the appropriate renderer module:

node archify/bin/archify.mjs deliver architecture my-diagram.json output.html --quality showcase --open

Key parameters include:

• <type>: Diagram type matching a renderer directory (e.g., architecture)
• <json>: Path to your validated JSON file
• <output.html>: Destination file path
• --open: Automatically launches the HTML in your default browser

The resulting HTML is entirely self-contained, requiring no external servers or CDN dependencies.

Using the Interactive Viewer

The generated HTML includes a full viewer UI with deterministic SVG rendering—the same JSON input always produces identical SVG markup. Interact with the diagram using these keyboard shortcuts:

• T: Toggle dark/light theme
• S: Cycle through visual presets (e.g., signal-flow, blueprint)
• E: Export to PNG, SVG, or WebM formats
• /: Focus mode (isolate specific components)
• R: Route probe (highlight connection paths)
• L: Lens mode (magnification)
• P, [, ]: Story navigation controls

These controls are implemented in the renderer modules (e.g., archify/renderers/architecture/render-architecture.mjs) and bound to the runtime specified in archify/references/viewer-runtime.md.

Working with Built-in Examples

Archify ships with pre-built examples to test rendering immediately. To render the built-in web application architecture demo:

node archify/bin/archify.mjs deliver architecture examples/web-app.architecture.json examples/web-app.html --open

The source JSON for this example lives at examples/web-app.architecture.json, while the pre-rendered HTML at examples/web-app.html demonstrates the final output. You can open examples/web-app.html directly in a browser without running any CLI commands to inspect the viewer capabilities.

Summary

• Install Archify globally using npx skills add tt-a1i/archify -g to access archify/bin/archify.mjs
• Define your system in JSON with nodes, edges, and meta fields matching schemas in archify/schemas/
• Validate with archify.mjs validate <type> <json> --quality showcase to catch layout errors early
• Render with archify.mjs deliver <type> <json> <output.html> --open to generate deterministic, interactive HTML
• Export diagrams via the viewer's E shortcut or use the "Copy Share Card" button for 1200×630 social images
• Extend support for architecture, workflow, sequence, dataflow, and lifecycle diagrams using dedicated renderers in archify/renderers/

Frequently Asked Questions

What JSON schema does Archify use for validation?

Archify validates against strict JSON schemas located in the archify/schemas/ directory. Each diagram type (architecture, workflow, sequence, dataflow, lifecycle) maintains its own schema definition that enforces required fields like id, kind, and connection references, ensuring the renderer can deterministically calculate SVG layouts.

Can I render diagrams without installing Archify globally?

Yes. While global installation via npx skills add is recommended for convenience, you can execute the CLI directly using local node paths. Reference the binary at node archify/bin/archify.mjs from within the project directory, or run validation and delivery commands using relative paths to your JSON files.

How do I export static images from Archify diagrams?

Press E while viewing the generated HTML to open the export menu, which supports downloading PNG, SVG, or WebM formats. Alternatively, use the "Copy Share Card" button in the viewer UI to generate a 1200×630 static image suitable for documentation or social sharing, all processed client-side without external API calls.

Is Archify's rendering process deterministic?

Yes. According to the source implementation in archify/renderers/*/render-*.mjs, the layout algorithms produce deterministic SVG markup—identical JSON inputs always generate identical HTML and SVG outputs. This guarantees reproducible visualizations across different machines and CI/CD pipelines.

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