# How to Render a Diagram Using the Archify CLI: A Complete Guide

> Learn to render diagrams with the Archify CLI. Follow our guide to create architecture, workflow, sequence, and more diagrams easily. Get started now.

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

---

**To render a diagram with Archify, run `node bin/archify.mjs render <type> <input>.json <output>.html` where `<type>` is your diagram type—architecture, workflow, sequence, data-flow, or lifecycle.**

Archify is an open-source diagramming tool that transforms typed **JSON IR (Intermediate Representation)** into production-ready, interactive HTML diagrams. The entire rendering pipeline is exposed through a single CLI entry point at `bin/archify.mjs`, making it easy to integrate diagram generation into CI/CD pipelines, documentation workflows, or local development environments.

## Understanding the Archify Rendering Pipeline

Before running commands, it helps to understand the four-stage pipeline the CLI executes:

1. **Generate JSON IR** – Create or obtain a typed JSON description of your diagram structure.
2. **Validate** – Built-in schema validators check JSON correctness before rendering.
3. **Render** – The chosen renderer produces a self-contained HTML file with embedded SVG, theme toggles, and export tools.
4. **Post-render checks** – Artifact verifiers ensure the SVG has finite coordinates, no accidental diagonal arrows, and no legend-crossing routes.

This pipeline guarantees that diagrams meet quality standards before they reach your documentation or presentations.

## The Core Render Command

The primary syntax for **rendering a diagram using the Archify CLI** follows this pattern:

```bash
node bin/archify.mjs render <type> <input>.json <output>.html

```

**Supported diagram types:**

- `architecture` – System and component diagrams
- `workflow` – Process and decision flows
- `sequence` – Interaction sequence diagrams
- `data-flow` – Data pipeline visualizations
- `lifecycle` – State and lifecycle diagrams

### Practical Example: Render a Workflow Diagram

As documented in the [README.md](https://github.com/tt-a1i/archify/blob/main/README.md#L253), the bundled examples demonstrate the CLI in action:

```bash
node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json workflow.html

```

This command reads the JSON IR from [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json) and outputs [`workflow.html`](https://github.com/tt-a1i/archify/blob/main/workflow.html)—a complete, interactive diagram.

### Render an Architecture Diagram

```bash
node bin/archify.mjs render architecture examples/archify-repo.architecture.json archify-repo.html

```

### Render a Data-Flow Diagram

```bash
node bin/archify.mjs render data-flow examples/product-analytics.dataflow.json dataflow.html

```

## Validating JSON Before Rendering

To catch errors early, use the `validate` subcommand. This checks your JSON IR against Archify's schema without generating output:

```bash
node bin/archify.mjs validate sequence examples/cache-miss-request.sequence.json --json

```

The `--json` flag returns machine-readable validation results, ideal for automated checks in pre-commit hooks or CI pipelines.

## Additional CLI Capabilities

Beyond rendering, `bin/archify.mjs` provides several utilities:

| Command | Purpose | Example |
|---------|---------|---------|
| `inspect` | Examine computed layouts and positioning | `node bin/archify.mjs inspect workflow input.json` |
| `demo` | Generate a full set of example diagrams | `node bin/archify.mjs demo /tmp/archify-demo` |
| `doctor` | Run health checks on your Archify installation | `node bin/archify.mjs doctor` |

### Run the Built-in Demo

The demo command generates example HTML files for all diagram types—useful for exploring capabilities or testing your installation:

```bash
node bin/archify.mjs demo /tmp/archify-demo

```

## Key Source Files for CLI Development

Understanding the codebase helps when customizing or debugging:

- **`bin/archify.mjs`** – Unified CLI entry point implementing all subcommands ([source](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs))
- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** – Agent documentation (Claude, Codex, OpenCode) with CLI usage patterns ([source](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md))
- **`archify/examples/*.json`** – Sample JSON IR files for every diagram type ([source](https://github.com/tt-a1i/archify/tree/main/archify/examples))
- **`archify/test/cli.test.mjs`** – Comprehensive test suite verifying CLI behavior across all commands ([source](https://github.com/tt-a1i/archify/blob/main/archify/test/cli.test.mjs))

## Integrating Archify into Automated Workflows

The single-entry CLI design simplifies automation. A typical CI pipeline might:

```bash

# Validate all JSON diagrams

node bin/archify.mjs validate architecture diagrams/*.json

# Render production artifacts

for file in diagrams/*.json; do
  name=$(basename "$file" .json)
  node bin/archify.mjs render architecture "$file" "output/$name.html"
done

```

Post-render checks ensure output quality without manual review.

## Summary

- **Primary command:** `node bin/archify.mjs render <type> <input>.json <output>.html`
- **Five diagram types:** architecture, workflow, sequence, data-flow, lifecycle
- **Validate first:** Use `validate` to catch JSON errors before rendering
- **Single entry point:** All commands run through `bin/archify.mjs`
- **Quality guaranteed:** Built-in post-render checks verify SVG correctness
- **CI-ready:** Clean syntax and exit codes enable full automation

## Frequently Asked Questions

### What file format does Archify output?

Archify generates **self-contained HTML files** that embed SVG diagrams, interactive theme toggles (light/dark), and export tools. The HTML requires no external dependencies and can be opened directly in any modern browser or hosted as static documentation.

### Can I render multiple diagrams at once?

The CLI processes one diagram per command, but you can script batch operations using shell loops or build tools. The consistent command structure—`node bin/archify.mjs render <type> <input> <output>`—makes this straightforward in CI pipelines or npm scripts.

### Where do I find example JSON files to start from?

Archify bundles complete examples for each diagram type in `archify/examples/`. These include [`agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/agent-tool-call.workflow.json), [`archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify-repo.architecture.json), [`cache-miss-request.sequence.json`](https://github.com/tt-a1i/archify/blob/main/cache-miss-request.sequence.json), and [`product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/product-analytics.dataflow.json). Use these as templates for your own diagrams.