How to Use the Archify CLI to Render a Diagram: A Complete Guide for Architecture and Workflow Visuals

The Archify CLI renders diagrams by running node archify/bin/archify.mjs preview <type> <source.json> <output.html> with built‑in validation and optional auto‑open.

Archify ships a zero‑dependency Node.js command‑line interface for transforming typed JSON sources into self‑contained HTML diagrams. Whether you need architecture diagrams, workflow flows, sequence charts, dataflows, or lifecycle visuals, the CLI handles validation, rendering, and output in a single command. This guide walks through the complete rendering workflow using the actual source implementation in tt-a1i/archify.

Locating the CLI Entry Point

The Archify CLI lives at archify/bin/archify.mjs. This file parses sub‑commands, validates inputs against schemas in archify/schemas/, and dispatches to specialized renderers under archify/renderers/.

No build step or external dependencies are required—Node.js alone runs the tool.

Supported Diagram Types

The CLI recognizes five diagram categories via the <type> positional argument:

• architecture – System component relationships and boundaries
• workflow – Process flows with decision points
• sequence – Interactions between actors over time
• dataflow – Information movement through pipelines
• lifecycle – State transitions and evolution stages

Each type triggers a dedicated renderer that produces deterministic SVG output embedded in HTML.

The Rendering Pipeline

When you run the preview command, the CLI executes four distinct phases:

1. Generate/Load – Reads your typed JSON intermediate representation (IR)
2. Validate – Applies built‑in validators for schema compliance, layout rules, and label‑route clearance
3. Render – Invokes the type‑specific renderer to produce HTML/SVG
4. Output – Writes the artifact to your specified path

The preview sub‑command is the recommended entry point for local diagram generation. Add --open to launch the result automatically, or --json to emit a machine‑readable receipt instead of HTML.

Core CLI Commands for Rendering

Render a Diagram to HTML

The foundational command validates your JSON and writes a self‑contained HTML file:

node archify/bin/archify.mjs preview architecture path/to/diagram.json output.html --quality showcase

The --quality flag selects a validation profile. showcase is the strictest, enforcing all layout and clearance rules.

Render and Open Automatically

Combine rendering with immediate browser launch using --open:

node archify/bin/archify.mjs preview architecture path/to/diagram.json output.html --quality showcase --open

Validate Without Rendering

Check your JSON against schemas and rules without generating output:

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

Returns a structured receipt suitable for CI pipelines.

Generate Starter JSON

Create a working template from a natural description:

node archify/bin/archify.mjs guide "Show an API request with a Redis cache miss" --json

The guide sub‑command uses the description to produce ready‑to‑render JSON IR.

Complete Working Examples

These commands demonstrate the full Archify CLI workflow as implemented in the repository:

# Generate starter JSON for an Architecture diagram

node archify/bin/archify.mjs guide "Use Archify to draw: Browser -> API -> Redis -> PostgreSQL" --json > my-diagram.json

# Render to HTML with strict validation (default dark theme)

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

# Render and open automatically

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

# Validate only, output JSON receipt

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

# Render a Workflow diagram from existing example

node archify/bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json workflow.html --quality showcase

Key Source Files and Their Roles

File	Purpose
archify/bin/archify.mjs	CLI entry point; parses sub‑commands and orchestrates the pipeline
archify/renderers/*	Type‑specific rendering engines for each diagram category
archify/schemas/	JSON Schema definitions for input validation
archify/SKILL.md	Formal contract specifying expected JSON IR and CLI behavior
README.md	Quick‑start reference with concrete command examples

Quality Profiles Explained

The --quality flag controls validation strictness:

• showcase – Maximum strictness; enforces all layout, spacing, and label clearance rules
• standard – Balanced validation for most use cases
• draft – Minimal checks for rapid iteration

Choose showcase when preparing diagrams for documentation or presentations where visual polish matters.

Output Format and Portability

Archify CLI produces self‑contained HTML files embedding:

• SVG vector graphics for crisp scaling at any resolution
• CSS styling (dark theme by default, customizable)
• Optional motion/animation scripts when supported by the diagram type

These files require no server, no external assets, and work offline—ideal for embedding in documentation, attaching to tickets, or sharing directly.

Summary

• Archify CLI location: archify/bin/archify.mjs
• Primary render command: preview <type> <source> <output> --quality showcase
• Five diagram types: architecture, workflow, sequence, dataflow, lifecycle
• Validation profiles: showcase (strictest), standard, draft
• Key flags: --open launches results; --json emits receipts; --quality sets validation level
• Output: Self‑contained HTML with embedded SVG, CSS, and optional motion

Frequently Asked Questions

What Node.js version does Archify CLI require?

The CLI runs on any Node.js version supporting ES modules (14+ recommended). No npm install or dependencies are needed—clone the repository and run directly.

Can I use Archify CLI in CI/CD pipelines?

Yes. Use the validate sub‑command with --json to emit machine‑readable receipts. Exit codes indicate validation success or failure, making it suitable for automated gates.

How do I customize the visual theme of rendered diagrams?

The CLI uses a default dark theme. Modify CSS variables in the generated HTML output, or override renderer defaults in archify/renderers/ source files for persistent changes.

What's the difference between preview and deliver commands?

preview renders and outputs HTML for local inspection. deliver performs the same rendering but marks the artifact as production‑verified, often with additional provenance metadata. Both accept identical flags in current implementations.

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