# How to Run the Archify Demo Pipeline: Complete CLI Guide

> Run the Archify demo pipeline with a simple CLI command to generate interactive architecture diagrams. Learn how to execute the demo and view results in your browser.

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

---

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

```bash

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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:

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

```

The CLI will automatically open [`archify-demo.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** – Declares skill capabilities including the demo command contract and deterministic rendering guarantees
- **[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)** – Schema reference used by validators when processing the demo's default JSON source
- **[`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/README_EN.md).

### What files does the demo command create?

The demo generates [`archify-demo.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md). The validation stage ensures any custom data conforms to layout rules and proof contracts before compilation proceeds.