How to Use the Archify CLI Preview Command: Complete Guide with Examples

The archify preview command generates an interactive HTML preview of any Archify workflow directly from the command line, allowing you to visualize diagrams without opening the web UI.

The Archify CLI provides a powerful preview sub-command that transforms workflow definitions into self-contained, browser-ready HTML files. This guide walks through installation, usage patterns, and advanced options based on the actual source code implementation in tt-a1i/archify.

---

What the Archify Preview Command Does

The archify preview command performs four core operations:

1. Parses and validates your workflow JSON/YAML file
2. Invokes the preview builder to assemble the HTML artifact
3. Injects runtime dependencies including the Archify renderer and UI controls
4. Writes the output to a specified location (default: ./preview.html)

The generated preview is identical to the web UI output because both use the same underlying runtime.

---

Basic Usage of Archify Preview

Command Structure

archify preview <workflow-file> [options]

Simple Example

# Generate preview for a workflow definition

archify preview my-workflow.json

# Result: creates ./preview.html in current directory

The CLI entry point at bin/archify.mjs routes the preview sub-command to the handler implemented in src/cli/preview.js.

---

Archify Preview Command Options

The preview command supports several flags defined in src/cli/flags.js:

Flag	Description	Default
--output <path>	Destination file path	preview.html
--theme <dark|light>	Force specific color theme	Auto-detected
--embed	Generate embed-friendly HTML (no chrome)	Disabled

Specify Custom Output Location

archify preview my-workflow.json --output docs/awesome.html

Force Light Theme

archify preview my-workflow.json --theme light --output public/preview.html

Generate Embed-Ready HTML

archify preview my-workflow.json --embed --output embeds/diagram.html

The --embed flag produces HTML suitable for iframe embedding, stripping navigation bars and surrounding UI chrome as demonstrated in examples/gallery-template.html.

---

Supported Input Formats

The preview command accepts workflow definitions in multiple formats:

# JSON workflow

archify preview workflow.json

# YAML workflow

archify preview workflow.yaml

The parser validates the workflow contract before rendering. Invalid files produce descriptive error messages without generating partial output.

---

Viewing the Generated Preview

macOS

archify preview my-workflow.json && open preview.html

Linux

archify preview my-workflow.json && xdg-open preview.html

Windows (PowerShell)

archify preview my-workflow.json; Start-Process preview.html

The output HTML is fully self-contained and can be opened directly in any modern browser without a local server.

---

Key Source Files in Archify

Understanding the implementation helps troubleshoot issues and extend functionality:

• bin/archify.mjs — CLI entry point; parses process.argv and dispatches to sub-commands
• src/cli/preview.js — Core preview command implementation, handles flag processing
• src/cli/flags.js — Flag definitions and validation schemas
• src/preview/builder.js — HTML generation logic; assembles runtime, data, and UI components
• archify/test/preview.test.mjs — Test suite verifying correct HTML output and flag handling

The builder in src/preview/builder.js injects:

• Workflow data as a serialized JavaScript object
• Archify runtime bundle for client-side rendering
• Theme switcher and navigation controls (unless --embed is used)

---

Troubleshooting Common Issues

Permission Denied on CLI

Ensure the binary is executable:

chmod +x bin/archify.mjs

# Or install globally

npm install -g @tt-a1i/archify

Invalid Workflow Errors

Validate your workflow schema before preview:

archify validate my-workflow.json && archify preview my-workflow.json

Missing Output File

Check write permissions in the target directory. The preview command does not create parent directories automatically.

---

Advanced: Programmatic Preview Generation

For CI/CD pipelines or custom tooling, invoke the builder directly:

import { buildPreview } from 'archify/src/preview/builder.js';

const html = await buildPreview({
  workflow: './workflow.json',
  theme: 'dark',
  embed: true
});

await fs.writeFile('output.html', html);

---

Summary

• The archify preview command generates interactive HTML previews from workflow definitions
• Default output is ./preview.html — customize with --output
• Use --embed for iframe-ready HTML without UI chrome
• The --theme flag forces dark or light mode regardless of system preference
• Preview output matches the web UI exactly because both share the same runtime
• Core implementation lives in src/cli/preview.js with builder logic in src/preview/builder.js

---

Frequently Asked Questions

What file formats does Archify preview support?

Archify preview accepts both JSON and YAML workflow definitions. The parser automatically detects the format from file extension and content structure. Invalid schemas produce validation errors before any HTML generation begins.

Can I use Archify preview without installing the full web UI?

Yes. The archify preview command is entirely self-contained. The generated HTML includes all necessary runtime code, making it portable and viewable in any browser without network access or local server requirements.

How do I automate preview generation in CI/CD?

Invoke archify preview with explicit output paths in your pipeline scripts. For programmatic control, import buildPreview from src/preview/builder.js directly. The test suite in archify/test/preview.test.mjs demonstrates reliable programmatic usage patterns.

Does the preview update automatically when my workflow changes?

No. The archify preview command generates static HTML. For live reloading during development, rerun the command after file changes or use a file watcher like chokidar-cli to trigger regeneration automatically.

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