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

> Easily generate Archify demos with the CLI demo command. Create ready to open HTML architecture diagrams and save them to your chosen directory.

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

---

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

```bash
node archify/bin/archify.mjs demo

```

This produces [`archify-demo.html`](https://github.com/tt-a1i/archify/blob/main/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.

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

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