# Archify Deliver vs Preview: Differences Between Production and Development CLI Commands

> Understand the key differences between Archify deliver and preview CLI commands. Deliver commits verified artifacts, while preview aborts before writing to disk.

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

---

**Both `archify deliver` and `archify preview` share an identical rendering pipeline, but `deliver` atomically commits a verified artifact while `preview` aborts before writing to disk.**

The `archify` CLI provides two commands for generating architecture diagrams from JSON definitions. Understanding when to use each ensures you get production-ready outputs without polluting your repository during development. This guide compares these commands based on the `tt-a1i/archify` source code, covering atomicity guarantees, receipts, side effects, and typical workflows.

## How the Rendering Pipeline Works

Both commands execute the same core stages: input validation, HTML rendering, quality checks, and artifact generation. The divergence occurs at the final commit step.

In `archify/bin/archify.mjs`, the CLI dispatcher routes to either command implementation. From there, `deliver` invokes a full delivery lifecycle while `preview` intercepts the process before the final write.

## Archify Deliver: Production-Ready Atomic Output

The `deliver` command is designed for **final, production-ready output** with strict correctness guarantees.

### Atomic Commit with Verification

According to `archify/test/cli.test.mjs` (lines 232–244), `deliver` uses a **candidate → verified swap pattern**:

1. Renders the HTML artifact to a temporary location
2. Runs all validation checks
3. Only replaces the target file after verification passes

This atomic operation ensures that a failed check never leaves a corrupted or partial file in place.

### Structured JSON Receipts

`deliver` emits a detailed receipt when using `--json`:

```bash
archify deliver architecture examples/arch.json out.html \
    --quality showcase --json

```

The receipt includes:
- The executed command string
- SHA-256 hash of the generated artifact
- Diagnostic output from checks
- Optional `--open` launch status

### Safe for CI and Automation

The command supports `--open` for interactive environments and runs without side effects in headless mode. This makes it **safe for CI pipelines, CD releases, and unattended agents**.

## Archify Preview: Interactive Debugging Without Side Effects

The `preview` command provides **interactive authoring and debugging** with identical visual output but no permanent changes.

### Non-Destructive Execution

As shown in `archify/test/preview.test.mjs` (lines 261–304), `preview` executes the full pipeline then **stops or drains the active delivery without publishing the artifact**. The repository remains unchanged regardless of check results.

```bash
archify preview architecture examples/arch.json out.html --json

```

The receipt reflects the preview execution only—there is no permanent artifact to hash or reference.

### Excluded from Watch Loops

Documentation in [`docs/research-next-delight-slice.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-next-delight-slice.md) (lines 60–79) emphasizes that `preview` is **intentionally independent** from `--watch` flags. The command stays short-lived to support rapid iteration without long-running processes.

### No File Opening

Unlike `deliver`, `preview` **never invokes an opener**. This prevents accidental browser launches during headless debugging sessions.

## Key Differences Between Deliver and Preview

| Aspect | `deliver` | `preview` |
|--------|-----------|-----------|
| **Commit behavior** | Atomic candidate → verified swap | Aborted before final write; no changes persisted |
| **Artifact output** | Permanent HTML file with SHA-256 verification | No file written to disk |
| **Receipt content** | Full production receipt with artifact hash | Execution-only receipt reflecting preview run |
| **Browser opening** | Supports `--open` flag | Never opens browser |
| **CI/CD suitability** | Fully supported | Not intended for automation |
| **Watch mode** | Can integrate with file watchers | Explicitly excluded from watch loops |

## When to Use Each Command

### Use `deliver` when:

- Publishing to production or staging environments
- Integrating with CI/CD pipelines
- Creating versioned, reproducible artifacts with receipts
- Running unattended automation

### Use `preview` when:

- Rapidly iterating on diagram design locally
- Debugging validation failures without file pollution
- Conducting design reviews before final commit
- Testing quality settings before production run

## Summary

- **`deliver`** and **`preview`** share identical rendering logic in `archify/bin/archify.mjs` but diverge at the commit stage.
- **`deliver`** performs an **atomic verified swap** in `archify/test/cli.test.mjs`, writing a permanent artifact with a SHA-256 receipt.
- **`preview`** **stops or drains the delivery** per `archify/test/preview.test.mjs` without modifying the filesystem.
- **`deliver`** supports `--open` and CI automation; **`preview`** is explicitly short-lived and independent per [`docs/research-next-delight-slice.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-next-delight-slice.md).

## Frequently Asked Questions

### Does preview generate the same HTML as deliver?

Yes. Both commands execute the identical rendering pipeline including validation and quality checks. The HTML produced in memory is bit-for-bit equivalent; `preview` simply discards it before writing to disk.

### Why does preview fail to write files even with --json?

The `--json` flag in `preview` emits an execution receipt, not an artifact reference. Since no file is committed, there is no SHA-256 hash or persistent path to include. This is intentional behavior to prevent accidental production contamination.

### Can I use preview in a CI pipeline?

No. `preview` is explicitly designed out of watch loops and automation contexts per [`docs/research-next-delight-slice.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-next-delight-slice.md). Use `deliver` for any automated or unattended workflow requiring deterministic outputs.

### What happens if checks fail during deliver?

The atomic candidate → verified swap ensures the previous artifact remains untouched. The receipt indicates failure status without leaving a partial or corrupted file. This safety guarantee is tested in `archify/test/cli.test.mjs`.