# How to Use Archify for Workflow Diagrams: Complete CLI and JSON Guide

> Learn to use Archify CLI and JSON to create interactive workflow diagrams from plain text. Validate preview and export your diagrams easily with this comprehensive guide.

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

---

**Archify converts plain-text process descriptions into interactive, theme-aware workflow diagrams through a typed JSON intermediate representation that you can validate, preview, and export.**

Archify is an open-source diagramming skill that supports five diagram types, with **workflow diagrams** being one of the most powerful for visualizing CI/CD pipelines, approval gates, and tool-call sequences. This guide walks you through creating workflow diagrams using the Archify CLI and the [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) specification.

---

## Installing Archify

Install the skill globally through any supported agent or package manager:

```bash
npx skills add tt-a1i/archify -g

```

This makes the `archify.mjs` CLI available for Cursor, Codex, Claude-Code, or Opencode environments.

---

## Creating Workflow Diagrams: The 5-Step Pipeline

Archify follows a structured pipeline from description to finished diagram. Each step has dedicated CLI commands in `archify/bin/archify.mjs`.

### Step 1: Describe the Process

Write a natural-language prompt that captures participants, ordered steps, decision points, and exception lanes. Example: *"Show an API request with Redis cache miss and approval gate."*

### Step 2: Generate JSON IR

Generate a JSON file with `diagram_type` set to `"workflow"`:

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

```

The output conforms to [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), containing `lanes`, `nodes`, `edges`, and optional `phases`/`groups`/`cards`.

### Step 3: Validate Against Schema

Ensure your JSON passes schema and layout checks:

```bash
node archify/bin/archify.mjs validate workflow <file>.json --quality showcase --json

```

The validator enforces **2 px clearance** for lane crossings and automatic port spreading to prevent overlapping arrows.

### Step 4: Preview Locally

Render to HTML for interactive inspection:

```bash
node archify/bin/archify.mjs preview workflow <file>.json /tmp/workflow.html --quality showcase

```

### Step 5: Deliver Final Artifact

Produce share-ready output with optional auto-open:

```bash
node archify/bin/archify.mjs deliver workflow <file>.json /tmp/workflow.html \
    --quality showcase --open --json

```

---

## Minimal Workflow JSON Example

Hand-craft or modify JSON following this structure from [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json):

```json
{
  "meta": { "diagram_type": "workflow", "visual_preset": "signal-flow" },
  "lanes": [
    { "id": "user", "label": "User Surface" },
    { "id": "agent", "label": "Agent Runtime" },
    { "id": "approval", "label": "Approval Boundary" },
    { "id": "tool", "label": "Tool Execution" }
  ],
  "nodes": [
    { "id": "requester", "lane": "user", "label": "Requester" },
    { "id": "router",   "lane": "agent", "label": "Router" },
    { "id": "gate",     "lane": "approval", "label": "Consent Gate", "type": "decision" },
    { "id": "executor", "lane": "tool", "label": "Executor" },
    { "id": "provider", "lane": "tool", "label": "External API" },
    { "id": "reply",    "lane": "user", "label": "Final Reply" }
  ],
  "edges": [
    { "source": "requester", "target": "router" },
    { "source": "router",    "target": "gate" },
    { "source": "gate",      "target": "executor", "label": "approved" },
    { "source": "executor",  "target": "provider" },
    { "source": "provider",  "target": "reply" }
  ],
  "cards": [
    { "node": "gate", "label": "Decision: approve?", "color": "rose" }
  ]
}

```

Save as [`my-workflow.json`](https://github.com/tt-a1i/archify/blob/main/my-workflow.json) and run validation/render commands. The viewer displays four horizontal lanes with a clear main path and visual decision highlighting.

---

## Interactive HTML Viewer Controls

Open the generated HTML in any browser. The viewer implemented in `archify/renderers/workflow/render-workflow.mjs` supports these keyboard shortcuts:

| Shortcut | Action |
|----------|--------|
| `/` | Search for a node |
| `R` | Probe routed path between two nodes |
| `L` | Open lens view for semantic role comparison |
| `T` | Toggle Light/Dark theme |
| `S` | Cycle visual presets (Signal Flow, Blueprint, Classic) |
| `E` | Open Export menu (PNG, SVG, WebM, Share Card) |

Additional features include **upstream/downstream reach** tracing and **deep-link anchors** (`#focus=…`) that restore exact focus when shared.

---

## Iterating on Workflow Diagrams

Archify supports incremental updates through succinct follow-up prompts. Examples that trigger targeted modifications:

- *"Add Redis cache layer between Router and Consent Gate"*
- *"Highlight the rollback path with dashed edges"*
- *"Split Tool Execution into two parallel lanes"*

The agent updates only affected nodes, edges, or lanes—preserving stable layout for unchanged elements.

---

## Export and Sharing Options

Final workflows support multiple output formats from the export menu (`E`):

- **PNG share cards** for social/documentation embedding
- **SVG** for scalable vector editing
- **WebM** for animated walkthroughs
- **Deep-link anchors** with focus state encoded in URL fragments

---

## Summary

- **Install** via `npx skills add tt-a1i/archify -g`
- **Generate** workflow JSON through `archify.mjs guide` or hand-craft to [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)
- **Validate** with `archify.mjs validate` to catch layout and schema errors
- **Preview** locally with `archify.mjs preview` before final delivery
- **Deliver** production artifacts via `archify.mjs deliver` with `--quality showcase`
- **Interact** using keyboard shortcuts in the HTML viewer for search, path probing, and theme toggling
- **Iterate** with natural-language prompts that preserve existing structure

---

## Frequently Asked Questions

### What is the workflow schema in Archify?

The **workflow schema** is a JSON Schema defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) that specifies required fields: `lanes` (horizontal tracks), `nodes` (process steps), `edges` (connections), and optional `phases`, `groups`, and `cards` for annotations. All workflow JSON must validate against this schema before rendering.

### How do I prevent overlapping arrows in Archify workflow diagrams?

The `render-workflow.mjs` renderer automatically enforces **2 px clearance** for lane crossings and spreads connection ports to eliminate overlaps. Run `archify.mjs validate` with `--quality showcase` to catch any remaining layout violations before delivery.

### Can I export Archify workflow diagrams to PNG or SVG?

Yes. Press `E` in the HTML viewer to open the **Export menu**, which offers PNG share cards, SVG vector output, WebM animations, and deep-link anchors. The `deliver` command also produces these formats programmatically.

### What keyboard shortcuts work in the Archify workflow viewer?

The viewer supports `/` for search, `R` for route probing, `L` for lens comparison, `T` for theme toggle, `S` for preset cycling, and `E` for export. These are documented in the README's **Viewer Cheatsheet** section.