# How to Deliver a Verified Artifact with the Archify CLI: A Complete Guide

> Learn how to deliver verified artifacts with the Archify CLI. Use the --quality flag to generate cryptographically verifiable receipts proving your diagram's origin. Inspect and open artifacts easily.

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

---

**Use the `--quality` flag with `archify preview` to generate a cryptographically verifiable receipt that proves your diagram was created from a specific repository revision, then inspect the receipt with `cat archify-receipt.json` and open the artifact with `archify open`.**

The **Archify CLI** transforms natural language prompts into interactive architecture diagrams backed by real source code. A **verified artifact** includes a JSON receipt that cryptographically attests to the diagram's provenance—every node links to a verifiable line in a specific repository revision. This guide walks through the exact commands, flags, and source code paths used to deliver verified artifacts.

## What Verification Means in Archify

Verification is not merely a visual check. According to the `tt-a1i/archify` source code, a verified artifact satisfies three guarantees:

- **Repository attestation**: The receipt records the exact URL and revision SHA
- **Node provenance**: Every diagram element links to a real source file and line range
- **Validation gate**: The CLI refuses to emit artifacts that fail these checks when `--quality showcase` is used

The validation logic resides in `archify/renderers/shared/validator.mjs`, while receipt generation is handled by `archify/renderers/shared/repository-evidence.mjs`.

## Installing the Archify CLI

The CLI is distributed via npm. The entry point is `archify/bin/archify.mjs`.

```bash
npm install -g archify

# Or use without installing:

npx archify

```

Verify installation by checking the help output:

```bash
archify --help

```

## Step 1: Generate a Verified Diagram with `--quality`

The `preview` command creates diagrams from natural language. To enable verification, append `--quality standard` or `--quality showcase`.

```bash
PROMPT="Show an API request with JWT auth, a Redis cache miss, a database fallback, and async tracing"

# Standard verification (receipt generated, validation warnings only)

archify preview "$PROMPT" --quality standard

# Showcase verification (hard failure if any node is unverifiable)

archify preview "$PROMPT" --quality showcase

```

The distinction between modes is enforced in `archify/bin/archify.mjs`. **Showcase quality** triggers strict validation—if any node lacks a resolvable source reference, the CLI exits non-zero and no artifact is emitted. This matches the behavior tested in `archify/test/real-repository-proof.test.mjs`.

The preview pipeline itself is orchestrated by `archify/bin/preview.mjs`, which delegates rendering to `archify/renderers/architecture/render-architecture.mjs` for architecture diagrams.

## Step 2: Inspect the Verification Receipt

After successful generation, Archify writes [`archify-receipt.json`](https://github.com/tt-a1i/archify/blob/main/archify-receipt.json) in the working directory. Example structure:

```json
{
  "verified": true,
  "repository": {
    "url": "https://github.com/owner/repo",
    "revision": "abc123def456..."
  },
  "referenceCount": 12,
  "nodes": [
    {
      "id": "jwt-middleware",
      "href": "https://github.com/owner/repo/blob/abc123/src/auth.js#L15-L42"
    }
  ],
  "semanticPassport": { ... }
}

```

Key fields explained:

- **`verified`**: Boolean flag set only after `validator.mjs` confirms all `href` values resolve to real lines
- **`revision`**: Full Git SHA, not a branch name, ensuring immutable provenance
- **`referenceCount`**: Total number of source-backed nodes in the diagram
- **`semanticPassport`**: Machine-readable metadata for downstream tooling (schema defined in `archify/renderers/shared/semantic-passport.test.mjs`)

Inspect the receipt directly:

```bash
cat archify-receipt.json | jq '.verified, .referenceCount'

```

If `verified` is `false` or absent, the artifact does not qualify as verified.

## Step 3: Open and Share the Verified Artifact

The CLI includes an `open` command to launch the HTML artifact:

```bash
archify open

```

This command is implemented in `archify/bin/open-artifact.mjs`. The generated HTML embeds the receipt and includes UI elements defined in [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html)—specifically the "Share a verified diagram" flow that submits showcase artifacts to the Archify gallery.

Archify artifacts are **self-contained**: all JavaScript, styles, and the verification receipt are bundled into a single file suitable for email, documentation, or permanent archival.

## Understanding the Validation Pipeline

For readers auditing the verification guarantees, here is the call chain through the source:

1. **`archify/bin/archify.mjs`** — Parses `--quality` flag, dispatches to preview or rejects invalid combinations
2. **`archify/bin/preview.mjs`** — Coordinates recipe parsing, rendering, and post-processing
3. **`archify/renderers/shared/validator.mjs`** — Performs the actual verification:
   - Fetches repository metadata
   - Resolves each node's `href` against the recorded revision
   - Sets `verified: true` only on 100% match
4. **`archify/renderers/shared/repository-evidence.mjs`** — Composes the final receipt payload

The automated test suite in `archify/test/real-repository-proof.test.mjs` asserts that this pipeline produces artifacts with valid receipts against real GitHub repositories.

## Common Verification Failures and Fixes

| Symptom | Cause | Resolution |
|---------|-------|------------|
| `verified: false` in receipt | One or more nodes link to non-existent files or lines | Run with `--quality standard` to see warnings, or fix source references in your prompt |
| CLI exits with error on `--quality showcase` | Strict validation failed | Check that your repository is public and the revision SHA exists |
| Missing [`archify-receipt.json`](https://github.com/tt-a1i/archify/blob/main/archify-receipt.json) | Generated with `--quality` omitted | Re-run with explicit `--quality standard` or `--quality showcase` |
| `referenceCount: 0` | Prompt produced no source-backed nodes | Refine prompt to mention specific files, functions, or architectural components |

## Quality Levels Compared

| Level | Verification | Use Case |
|-------|-----------|----------|
| **(none)** | No receipt generated | Quick iteration, local exploration |
| **`standard`** | Receipt generated, warnings on failures | Internal documentation, CI pipelines |
| **`showcase`** | Hard validation gate, must pass for artifact emission | Public gallery submissions, audit requirements, legal evidence |

The quality parameter directly controls `validator.mjs` invocation and exit behavior as implemented in the main entry point.

## Summary

- **Install** via `npm i -g archify` — entry point is `archify/bin/archify.mjs`
- **Generate** verified diagrams with `archify preview "your prompt" --quality standard|showcase`
- **Validate** that [`archify-receipt.json`](https://github.com/tt-a1i/archify/blob/main/archify-receipt.json) contains `"verified": true` and expected `referenceCount`
- **Open** the self-contained HTML artifact with `archify open`
- **Share** through the embedded gallery submission UI or direct file distribution

The verification guarantee is enforced by `archify/renderers/shared/validator.mjs` and recorded by `archify/renderers/shared/repository-evidence.mjs`, with showcase-grade artifacts requiring 100% node provenance.

## Frequently Asked Questions

### What makes an Archify artifact "verified"?

A verified artifact includes a JSON receipt with `"verified": true`, generated only after `archify/renderers/shared/validator.mjs` confirms every diagram node links to a real source file at a specific revision. The receipt includes repository URL, Git SHA, reference count, and a semantic passport for machine verification.

### Can I verify artifacts from private repositories?

The open-source CLI validates against any accessible Git repository. For private repositories, ensure the runtime environment has appropriate credentials. The validator performs live URL resolution; if it can fetch the source, it can verify the reference. The gallery submission UI in [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html) may have additional policies.

### Why does `--quality showcase` fail when `--quality standard` succeeds?

Showcase mode enforces a hard validation gate in `archify/bin/archify.mjs`: any unverifiable node causes immediate exit with non-zero status. Standard mode generates the receipt but tolerates partial verification failures. Use showcase for public, audit, or legal contexts where proof of provenance is mandatory.

### How can I programmatically consume verification results?

Parse [`archify-receipt.json`](https://github.com/tt-a1i/archify/blob/main/archify-receipt.json). The schema is tested in `archify/renderers/shared/semantic-passport.test.mjs`. Key fields: `verified` (boolean), `repository.revision` (string), `referenceCount` (integer), and `nodes[].href` (array of source URLs). The receipt is suitable for CI gates, SBOM tooling, or compliance documentation.