Preview Mode vs Deliver Command in Archify: Key Differences Explained

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

# Deliver a validated, showcase-quality architecture diagram

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

This produces:

{
  "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.

# 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:

{
  "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 (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:

# 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.

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