Archify CLI Commands Reference for validate, deliver, preview, and compare

The Archify CLI commands reference for validate, deliver, preview, and compare is documented across three locations in the repository: the README "Useful repository commands" section, the SKILL.md specification file, and the archify/bin/archify.mjs source file itself.

All four commands are implemented in this open-source architecture diagram generator. Whether you need to validate JSON IR files, render final outputs, preview work in progress, or compare architectural versions, the reference material lives directly in the codebase.

---

Quick Reference: The Three Primary Documentation Sources

You do not need to search external sites for the Archify CLI commands reference. Everything you need is contained in these three files:

• README.md — High-level quick-start with concrete examples for all four commands
• archify/SKILL.md — Formal CLI specification with canonical syntax patterns
• archify/bin/archify.mjs — Source implementation showing each sub-command's options and defaults

Together, these files provide complete coverage of validate, deliver, preview, and compare functionality.

---

Validate Command Reference

The validate command checks a JSON IR file against Archify's quality standards and outputs a machine-readable receipt.

Syntax and Flags

As documented in archify/SKILL.md and demonstrated in archify/bin/archify.mjs, the pattern is:

node archify/bin/archify.mjs validate <type> <candidate.json> [--quality <level>] [--json]

Example Usage

# Validate a workflow diagram with full quality checks and JSON output

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
  --quality showcase --json

The --quality flag accepts showcase for production-ready diagrams. The --json flag formats the receipt for programmatic consumption. See the implementation in archify/bin/archify.mjs for additional validation logic.

---

Deliver Command Reference

The deliver command combines rendering, quality checking, and optional browser opening into a single operation.

Syntax and Flags

From archify/SKILL.md:

node archify/bin/archify.mjs deliver <type> <candidate.json> <output.html> [--quality <level>] [--open] [--json]

Example Usage

# Render, validate, and open the result in a browser

node archify/bin/archify.mjs deliver architecture examples/web-app.json /tmp/web-app.html \
  --quality showcase --open --json

The --open flag triggers automatic browser launch after successful generation. This command is the recommended path for final artifact production.

---

Preview Command Reference

The preview command launches a local development server with watch-mode regeneration for rapid iteration.

Syntax and Flags

Documented in both README.md and archify/SKILL.md:

node archify/bin/archify.mjs preview <type> <candidate.json> <output.html> [--quality <level>]

Example Usage

# Live-reload preview for a dataflow diagram

node archify/bin/archify.mjs preview dataflow examples/dataflow-product-analytics.json \
  /tmp/dataflow.html --quality showcase

Unlike deliver, preview does not accept --open or --json flags in typical usage. The implementation in archify/bin/archify.mjs handles filesystem watching and incremental rebuilds.

---

Compare Command Reference

The compare command generates an Architecture Delta report between two validated JSON IR snapshots.

Syntax and Flags

As shown in archify/bin/archify.mjs and the README's "Architecture Delta" section:

node archify/bin/archify.mjs compare <type> <base.json> <head.json> <output.html> [--json]

Example Usage

# Compare base and head versions, outputting structured JSON metadata

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html \
  --json

This command requires both input files to have passed validate previously. The output HTML contains visual diff markers showing structural changes between versions.

---

Supported Diagram Types

All four commands accept the same <type> argument. As defined in the source, valid values include:

• architecture — System component diagrams
• workflow — Process and decision flows
• sequence — Interaction timelines
• dataflow — Data movement pipelines
• lifecycle — State transition diagrams

The type determines which validation rules and rendering templates apply.

---

Where to Find Each Reference Document

File Path	Content Focus	Best For
README.md	Quick-start examples, Architecture Delta explanation	First-time users, copy-paste ready commands
archify/SKILL.md	Canonical syntax patterns, formal flag definitions	Understanding exact CLI contracts
archify/bin/archify.mjs	Source implementation, default values, option parsing	Debugging behavior, discovering edge-case flags

---

Summary

• The Archify CLI commands reference for validate, deliver, preview, and compare lives entirely within the repository
• Start with README.md for working examples you can run immediately
• Consult archify/SKILL.md for precise syntax and flag semantics
• Read archify/bin/archify.mjs to understand implementation details and default behaviors
• All commands follow the pattern node archify/bin/archify.mjs <command> <type> <inputs> [options]

---

Frequently Asked Questions

Where is the official Archify CLI documentation hosted?

There is no external documentation site. According to the tt-a1i/archify repository structure, all CLI reference material is maintained in README.md, archify/SKILL.md, and the source file archify/bin/archify.mjs. These files are version-controlled alongside the code and always reflect the current implementation.

What is the difference between deliver and preview?

deliver is for final artifact generation: it validates, renders, and optionally opens the result. preview is for active development: it starts a watch-mode server that regenerates output when source files change. The preview command skips the --open and --json flags used by deliver, as shown in archify/bin/archify.mjs.

Do I need to validate files before running compare?

Yes. The compare command expects both base.json and head.json to be validated snapshots. The README's Architecture Delta section and the implementation in archify/bin/archify.mjs assume prior successful validate runs on both inputs.

How do I get machine-readable output from these commands?

Add the --json flag to validate, deliver, or compare. This outputs structured receipt metadata to stdout. The preview command does not support --json because its primary output is a filesystem-watched HTML file, not a one-shot execution result.

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