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

> Easily deliver your finished Archify diagram artifact using the command line. Learn the complete CLI guide for showcasing your workflows with Archify.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-29

---

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json)
- **`<output-html-file>`** — Destination for the generated HTML artifact. Example: [`/tmp/workflow.html`](https://github.com/tt-a1i/archify/blob/main//tmp/workflow.html) or [`./artifacts/diagram.html`](https://github.com/tt-a1i/archify/blob/main/./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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json)
- Writes to [`/tmp/agent-tool-call.html`](https://github.com/tt-a1i/archify/blob/main//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)

```bash
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`](https://github.com/tt-a1i/archify/blob/main/README.md)** — Official documentation with annotated command examples
- **[`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/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`.