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

> Master the Archify CLI preview command to generate interactive HTML workflows directly from your terminal. Visualize diagrams instantly without the web UI. Get the complete guide with examples.

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

---

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

```bash
archify preview <workflow-file> [options]

```

### Simple Example

```bash

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

---

## Archify Preview Command Options

The preview command supports several flags defined in [`src/cli/flags.js`](https://github.com/tt-a1i/archify/blob/main/src/cli/flags.js):

| Flag | Description | Default |
|------|-------------|---------|
| `--output <path>` | Destination file path | [`preview.html`](https://github.com/tt-a1i/archify/blob/main/preview.html) |
| `--theme <dark\|light>` | Force specific color theme | Auto-detected |
| `--embed` | Generate embed-friendly HTML (no chrome) | Disabled |

### Specify Custom Output Location

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

```

### Force Light Theme

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

```

### Generate Embed-Ready HTML

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

---

## Supported Input Formats

The preview command accepts workflow definitions in multiple formats:

```bash

# 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

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

```

### Linux

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

```

### Windows (PowerShell)

```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`](https://github.com/tt-a1i/archify/blob/main/src/cli/preview.js)** — Core preview command implementation, handles flag processing
- **[`src/cli/flags.js`](https://github.com/tt-a1i/archify/blob/main/src/cli/flags.js)** — Flag definitions and validation schemas
- **[`src/preview/builder.js`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
chmod +x bin/archify.mjs

# Or install globally

npm install -g @tt-a1i/archify

```

### Invalid Workflow Errors

Validate your workflow schema before preview:

```bash
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:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/./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`](https://github.com/tt-a1i/archify/blob/main/src/cli/preview.js) with builder logic in [`src/preview/builder.js`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.