How to Generate Archify Demos: A Complete Guide to the CLI Demo Command

The archify demo [output-directory] command creates a ready-to-open HTML file containing a sample architecture diagram, optionally placing it in a custom directory.

This guide walks you through generating Archify demos using the built-in CLI tool. Whether you want a quick preview in your current folder or a custom location for sharing, the demo command handles directory creation, HTML rendering, and PNG asset generation automatically. The implementation is located in archify/bin/archify.mjs according to the tt-a1i/archify source code.

Understanding the Archify Demo Command Structure

The demo subcommand follows a straightforward pattern inherited from Archify's CLI design.

In archify/bin/archify.mjs, the CLI usage description at lines 30-33 documents the demo command's purpose:

• Run without arguments → creates archify-demo.html in the current working directory
• Run with a directory path → creates the folder if needed and places the demo inside

The core implementation resides around lines 1470-1490, where the command:

1. Parses the optional output directory argument
2. Creates the directory structure using Node.js filesystem APIs
3. Builds a minimal architecture JSON internally
4. Renders it with the default "architecture" renderer
5. Writes the interactive HTML file plus three supporting PNG assets

Generating a Demo in the Current Directory

The simplest approach generates the demo exactly where you run the command.

node archify/bin/archify.mjs demo

This produces archify-demo.html in your current working directory. Open it in any modern browser to interact with the sample architecture diagram—no JSON writing required.

Creating a Demo in a Custom Directory

Specify a path to organize demos separately from your project files.

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

Archify automatically:

• Creates /tmp/my-archify-demo if it doesn't exist
• Handles filesystem errors gracefully (permissions, invalid paths, etc.)
• Places archify-demo.html inside the specified folder

The same three PNG assets (story, route, and lens diagrams) are generated adjacent to the HTML file for complete offline functionality.

Automating Demo Generation in Scripts

Integrate demo creation into build pipelines or documentation workflows.

import { spawnSync } from 'node:child_process';

const result = spawnSync('node', [
  'archify/bin/archify.mjs',
  'demo',
  '/tmp/demo-output'
]);

if (result.status === 0) {
  console.log('Demo generated successfully');
  console.log('Output:', result.stdout.toString());
}

The command exits with status 0 on success, making it compatible with CI/CD validation steps.

Where Demo Assets Are Stored and Tested

Generated demos reference three PNG visualizations that are also maintained in the repository:

Asset Purpose	File Pattern	Location
Story diagram	archify-demo-story.png	docs/assets/
Route diagram	archify-demo-route.png	docs/assets/
Lens diagram	archify-demo-lens.png	docs/assets/

These assets are verified by two test suites in tt-a1i/archify:

• archify/test/cli.test.mjs — confirms the demo command creates valid HTML output
• archify/test/readme-showcase.test.mjs — validates that demo assets exist, have correct dimensions, and are properly linked in README.md

The README's demo section displays live examples with deep-link URLs pointing to these generated artifacts.

Summary

• Archify demo generation uses the archify demo [output-directory] CLI command defined in archify/bin/archify.mjs
• Running without arguments creates archify-demo.html in the current directory; providing a path creates that directory first
• The implementation handles directory creation, error handling, and writes both HTML and three PNG assets (lines 1470-1490)
• Generated demos use the default "architecture" renderer with a built-in sample JSON structure
• Test coverage in cli.test.mjs and readme-showcase.test.mjs ensures reliability

Frequently Asked Questions

What files does the Archify demo command create?

The command generates four files: archify-demo.html (the interactive diagram) plus three PNG images (story, route, and lens visualizations). These are written to your specified directory or the current working directory. The HTML file is self-contained and opens directly in browsers without a server.

Can I customize the sample diagram that the demo generates?

No—the demo command uses a hardcoded minimal architecture JSON built internally. For custom diagrams, write your own JSON file and use archify render <file> instead. The demo command exists specifically for quick, zero-configuration previews of Archify's rendering capabilities.

Does the demo command support a --watch or --open flag?

The demo command does not natively accept --open or --watch flags per the source code at lines 30-33. To open the generated file automatically, chain a platform-specific command: node archify/bin/archify.mjs demo /tmp/demo && open /tmp/demo/archify-demo.html (macOS) or xdg-open (Linux).

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