How to Run the Archify Demo Pipeline: Complete CLI Guide

Run the Archify demo pipeline by executing node archify/bin/archify.mjs demo <output-directory> to generate a deterministic interactive architecture diagram, optionally adding --open to launch it automatically in your browser.

Archify is an open-source visualization engine for software architecture maintained at tt-a1i/archify. Running the demo pipeline allows you to evaluate its capabilities without writing custom JSON source files. This guide covers the exact CLI commands, source file locations, and pipeline stages used to produce the default architecture example.

What the Archify Demo Pipeline Does

The demo pipeline implemented in archify/bin/archify.mjs follows the same generate‑validate‑deliver workflow used for production renders. It executes four deterministic stages:

• Generate – Creates a deterministic intermediate representation (IR) from a default typed JSON description
• Validate – Runs built-in validators against schema constraints, layout rules, and proof contracts
• Deliver – Compiles the verified IR into HTML/SVG assets with optional PNG/WebM thumbnails; only passing artifacts replace previous output to guarantee a last-good file
• Open – When invoked with --open, launches the HTML viewer in your default browser

Because the pipeline is deterministic, every execution produces identical output, making it ideal for documentation screenshots, CI tests, and tutorial baselines.

Prerequisites and Installation

Installing Archify Globally

Before running the demo, install the skill globally for your AI agent environment (Cursor, Claude, Codex, etc.):

# Interactive installation

npx skills add tt-a1i/archify -g

# Silent installation for CI or automated setups

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

This registers the archify CLI and makes the entry point at archify/bin/archify.mjs accessible from your project path.

Executing the Demo Command

Basic Demo Run

To generate the demo output into a directory of your choice:

node archify/bin/archify.mjs demo /tmp/archify-demo

This command:

1. Creates /tmp/archify-demo/ if it does not exist
2. Writes archify-demo.html containing the interactive viewer
3. Populates supporting assets including PNG thumbnails and the JSON source snapshot

Auto-Opening the Result

Append the --open flag to launch the diagram immediately after generation:

node archify/bin/archify.mjs demo /tmp/archify-demo --open

The CLI will automatically open archify-demo.html in your default browser once validation and asset compilation succeed.

Exploring the Generated Interactive Diagram

The demo produces a fully-featured HTML viewer implementing the complete Archify UI:

• Search – Filter nodes and edges dynamically
• Focus mode – Isolate specific architectural components
• Route probing – Trace dependency paths
• Lens controls – Adjust zoom and viewport
• Keyboard shortcuts:
  • T – Toggle light/dark themes
  • S – Cycle through visual presets (styles)
  • P – Play the guided story packaged with the demo data

The output directory remains self-contained; you can archive or serve archify-demo.html standalone without the Archify toolchain installed.

Key Source Files in the Pipeline

Understanding the repository structure helps when customizing the demo or debugging pipeline stages:

• archify/bin/archify.mjs – Main CLI entry point that parses the demo sub-command and orchestrates generate→validate→deliver stages
• archify/SKILL.md – Declares skill capabilities including the demo command contract and deterministic rendering guarantees
• archify/schemas/README.md – Schema reference used by validators when processing the demo's default JSON source
• examples/archify-repo.html – Reference implementation showing the full feature set; the demo command produces a structurally identical artifact with synthesized data

These paths are documented in the repository's README_EN.md under the Quick Start sections for installation (line 96) and demo execution (line 1009).

Summary

• Run the Archify demo pipeline with node archify/bin/archify.mjs demo <dir> to generate a deterministic architecture diagram
• Add --open to automatically launch the HTML viewer in your browser
• The pipeline executes Generate → Validate → Deliver stages defined in archify/bin/archify.mjs to ensure schema-compliant output
• Output includes archify-demo.html plus supporting assets in a self-contained directory
• Deterministic rendering guarantees identical output across runs, ideal for regression testing and documentation

Frequently Asked Questions

Where is the Archify demo pipeline implemented?

The pipeline logic resides in archify/bin/archify.mjs, which handles command parsing, IR generation, validation against schemas defined in archify/schemas/README.md, and final HTML compilation. This entry point is referenced in the repository's quick-start documentation at line 1009 of README_EN.md.

What files does the demo command create?

The demo generates archify-demo.html (the interactive viewer), PNG thumbnail assets in a docs/assets/ subdirectory, and a JSON source snapshot reflecting the default architecture example. All outputs are written to the directory path you specify in the CLI command.

Can I automate the demo in CI pipelines?

Yes. The deterministic nature of the generate‑validate‑deliver workflow makes it suitable for continuous integration. Use the silent install command with --yes and omit --open to generate artifacts without browser dependencies, then archive the output directory for screenshot comparison or deployment.

How do I customize the demo output?

While the demo uses a built-in typed JSON description, you can modify the IR generation logic in archify/bin/archify.mjs or supply your own source files following the schema documented in archify/schemas/README.md. The validation stage ensures any custom data conforms to layout rules and proof contracts before compilation proceeds.

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