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

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 specification.

---

Installing Archify

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

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

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

The output conforms to 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:

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:

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:

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:

{
  "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 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
• 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 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.

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