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

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:

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.

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

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

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