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

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:

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, the bundled examples demonstrate the CLI in action:

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 and outputs workflow.html—a complete, interactive diagram.

Render an Architecture Diagram

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

Render a Data-Flow Diagram

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:

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:

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)
• archify/SKILL.md – Agent documentation (Claude, Codex, OpenCode) with CLI usage patterns (source)
• archify/examples/*.json – Sample JSON IR files for every diagram type (source)
• archify/test/cli.test.mjs – Comprehensive test suite verifying CLI behavior across all commands (source)

Integrating Archify into Automated Workflows

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

# 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, archify-repo.architecture.json, cache-miss-request.sequence.json, and product-analytics.dataflow.json. Use these as templates for your own diagrams.

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