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

> Learn to render diagrams with the Archify CLI using a simple command. Visualize your architecture and workflows efficiently with built-in validation and auto-open options.

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

---

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

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

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

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

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

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Formal contract specifying expected JSON IR and CLI behavior |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/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.