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

> Render interactive system diagrams from JSON using Archify CLI. Validate schemas and deliver HTML/SVG visualizations with built-in viewer controls. Explore tt-a1i/archify.

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

---

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

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

```json
{
  "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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/archify/templates/viewer.html) and injects deterministic SVG markup generated by the appropriate renderer module:

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json), while the pre-rendered HTML at [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) demonstrates the final output. You can open [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/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.