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

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.

npm install -g archify

# Or use without installing:

npx archify

Verify installation by checking the help output:

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.

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 in the working directory. Example structure:

{
  "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:

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:

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

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