How to Deliver a Finished Archify Diagram Artifact: The Complete CLI Guide

Deliver a completed Archify diagram artifact with node bin/archify.mjs deliver workflow <input.json> <output.html> --quality showcase.

Archify is an open-source diagram generator that packages architecture visualizations into self-contained HTML files. When your diagram is ready for distribution, the deliver sub-command handles validation, rendering, and optional browser preview in a single atomic operation. This guide explains the complete command syntax, available options, and verification methods based on the official tt-a1i/archify source code.

What the deliver Command Does

The deliver sub-command in archify/bin/archify.mjs performs three critical steps before producing your artifact:

1. Validates the input JSON against Archify's workflow schema
2. Renders the diagram into a standalone HTML file with embedded assets
3. Generates a cryptographic receipt for traceability

All validation must pass before the output file is written. If any check fails, Archify aborts without producing a partial artifact and instead emits a repair receipt for debugging.

Full Command Syntax

node bin/archify.mjs deliver workflow <path-to-workflow-json> <output-html-file> [options]

Required Arguments

• workflow — Specifies the input type. Archify supports multiple diagram types, with workflow being the most common for agent and process visualizations.
• <path-to-workflow-json> — Path to your diagram definition. Example: examples/agent-tool-call.workflow.json
• <output-html-file> — Destination for the generated HTML artifact. Example: /tmp/workflow.html or ./artifacts/diagram.html

Common Options

Option	Purpose
--quality showcase	Enables strictest validation for polished, production-ready artifacts
--open	Automatically launches the HTML in your default browser after delivery
--json	Outputs a machine-readable receipt with SHA-256 hash and metadata

These options appear in the official README at lines 214–221.

Practical Examples

Basic Delivery with Browser Preview

node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json \
    /tmp/agent-tool-call.html --quality showcase --open --json

This command:

• Processes examples/agent-tool-call.workflow.json
• Writes to /tmp/agent-tool-call.html
• Validates against showcase-quality standards
• Opens the result in your browser
• Prints JSON receipt to stdout

CI-Friendly Delivery (No Browser)

node bin/archify.mjs deliver workflow examples/web-app.workflow.json \
    ./artifacts/web-app.html --quality showcase --json

Omit --open for automated pipelines where no display is available. The JSON receipt still provides verification data.

Understanding the JSON Receipt

When --json is specified, Archify outputs a receipt object containing:

• SHA-256 hash — Cryptographic fingerprint of the generated HTML
• File size — Byte count for integrity verification
• Validation results — Pass/fail status for all quality checks

This receipt enables downstream automation. The scripts/package-smoke.mjs file in the repository demonstrates how to parse receipts in test harnesses.

Delivery Quality Profiles

The --quality parameter controls validation strictness:

• showcase — Maximum validation for stakeholder presentations and documentation. Recommended for all deliveries unless you specifically need faster iteration.
• (Additional profiles may be available; consult archify/bin/archify.mjs for current options.)

Key Source Files

Understanding these files deepens your command-line fluency:

• archify/bin/archify.mjs — CLI entry point that parses deliver, validate, render, and other sub-commands
• README.md — Official documentation with annotated command examples
• examples/agent-tool-call.workflow.json — Reference workflow used in official examples
• scripts/package-smoke.mjs — Test implementation showing receipt verification

Troubleshooting Failed Deliveries

If validation fails, Archify aborts without writing the HTML. Instead, you receive a repair receipt indicating which checks failed. Common causes include:

• Malformed JSON in the workflow definition
• Missing required diagram elements
• Invalid cross-references between nodes

Fix the underlying issue and re-run the deliver command. The atomic design prevents corrupted artifacts from reaching your output directory.

Summary

• Primary command: node bin/archify.mjs deliver workflow <input> <output> --quality showcase
• Essential flags: --open for browser preview, --json for verification receipts
• Atomic guarantee: Validation must pass before HTML is written
• Self-contained output: Single HTML file with embedded assets, ready for distribution

Frequently Asked Questions

What file format does Archify deliver?

Archify delivers fully self-contained HTML files with all CSS, JavaScript, and diagram data embedded. No external dependencies or network requests are required to view the artifact.

How do I automate Archify delivery in CI/CD?

Omit the --open flag and use --json to capture structured output. Parse the receipt to verify the SHA-256 hash and validation status before promoting the artifact to subsequent pipeline stages.

What happens if validation fails during delivery?

The command aborts without writing the HTML file. A repair receipt is emitted to stderr instead, identifying which validation checks failed. Fix the issues in your workflow JSON and re-run the command.

Can I deliver multiple diagram types with the same command?

The workflow argument specifies the diagram type. Archify may support additional types; check archify/bin/archify.mjs for currently implemented sub-commands beyond deliver workflow.

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