# Preview Mode vs Deliver Command in Archify: Key Differences Explained

> Understand the key differences between Archify's preview mode and deliver command. Learn how preview runs the pipeline without committing and deliver provides validated atomic output with a receipt.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-15

---

**The `archify preview` command runs the full rendering pipeline without committing the artifact, while `archify deliver` produces a validated, atomic output with a permanent receipt.**

Both commands in the Archify CLI share identical rendering logic, but they diverge sharply at the final commit stage. Understanding this distinction helps you choose the right tool for CI automation versus local authoring workflows.

## Core Architecture: Shared Pipeline, Divergent Outputs

In `archify/bin/archify.mjs`, both commands dispatch through the same internal rendering engine. The difference lies in what happens after validation completes.

### How Deliver Commits Atomically

The `deliver` command implements a **candidate → verified swap** pattern. As tested in `archify/test/cli.test.mjs` (lines 232-244), it:

1. Renders the HTML artifact to a temporary candidate location
2. Runs all quality checks and diagnostics
3. Only replaces the target file after verification passes
4. Writes a structured JSON receipt with SHA-256 hash

```bash

# Deliver a validated, showcase-quality architecture diagram

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

```

This produces:

```json
{
  "command": "deliver",
  "status": "pass",
  "artifact": "out.html",
  "sha256": "a3f7c2...",
  "diagnostics": []
}

```

### How Preview Aborts Before Write

The `preview` command intentionally **stops or drains** the delivery before atomic commit. The test suite in `archify/test/preview.test.mjs` (lines 261-304) verifies this behavior: the pipeline executes fully, then the delivery is terminated without writing the permanent artifact.

```bash

# Preview without committing the result

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

```

The receipt reflects execution only—no artifact hash, no permanent file:

```json
{
  "command": "preview",
  "status": "drained",
  "note": "delivery stopped before commit"
}

```

## Side-by-Side Comparison

| Capability | `deliver` | `preview` |
|------------|-----------|-----------|
| **Artifact persistence** | Atomic commit with SHA-256 verification | No write; repository unchanged |
| **Receipt content** | Full artifact metadata with hash | Execution-only summary |
| **`--open` flag** | Launches generated HTML in browser | Disabled; no opener invoked |
| **CI safety** | Designed for unattended environments | Excluded from watch loops |
| **Typical use** | Production releases, CI pipelines | Local debugging, design reviews |

## When to Use Each Command

### Use `deliver` for Final Outputs

According to the Archify source code, `deliver` is built for **non-interactive reliability**:

- CI/CD pipelines requiring versioned artifacts
- Automated releases where failure must be atomic
- Scripts that need the `--open` launcher for verification

The command never leaves partial files. If validation fails, the candidate is discarded and the target remains untouched.

### Use `preview` for Rapid Iteration

As documented in [`docs/research-next-delight-slice.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-next-delight-slice.md) (lines 60-79), `preview` serves **interactive authoring**:

- Quick visual checks without polluting the workspace
- Debugging a delivery configuration before committing
- Design reviews where multiple iterations are expected

The command stays intentionally short-lived. It does not support `--watch` mode and exits immediately after pipeline completion.

## Practical Workflow Example

Combine both commands in a typical development cycle:

```bash

# Iterate quickly with preview

archify preview architecture draft.json --quality draft

# Validate and commit when satisfied

archify deliver architecture draft.json final.html \
    --quality showcase --open --json

```

## Summary

- **`deliver`** produces atomic, verifiable artifacts with SHA-256 receipts—ideal for CI and production
- **`preview`** executes the same pipeline but aborts before commit—perfect for local debugging
- Both commands share source code in `archify/bin/archify.mjs` but diverge at the final write stage
- Key implementation details live in `archify/test/cli.test.mjs` and `archify/test/preview.test.mjs`

## Frequently Asked Questions

### Does preview generate any files at all?

`archify preview` may create temporary working files during rendering, but it never commits the final HTML artifact. The repository remains unchanged after execution, as confirmed by the drain/stop logic in `archify/test/preview.test.mjs`.

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

No. The `preview` command is explicitly designed for interactive use. It lacks atomic guarantees, disables the `--open` flag, and is excluded from watch loops. For CI environments, always use `archify deliver` with its verified artifact and JSON receipt.

### Why do both commands accept the same arguments?

They share the rendering pipeline defined in the CLI entry point. This consistency lets you swap `preview` for `deliver` (or vice versa) without changing quality settings, input paths, or output specifications—only the commit behavior changes.

### How do I verify a deliver artifact was written correctly?

Check the JSON receipt. Successful deliveries include a `sha256` field you can use to validate file integrity. The atomic swap in `deliver` ensures the hash matches the committed file exactly.