Archify CLI Commands: Complete Reference for Diagram Lifecycle Management

The Archify CLI provides 15 specialized sub-commands—including render, compare, deliver, preview, validate, and inspect—accessible via the archify/bin/archify.mjs entry point to manage the complete diagram lifecycle from JSON IR to deterministic HTML artifacts.

The tt-a1i/archify repository ships a single-purpose command-line interface that transforms typed JSON intermediate representations into validated HTML and SVG diagrams. Mastering the available Archify CLI commands enables automated documentation pipelines, deterministic architecture reviews, and automated visual regression testing.

Core Rendering Commands

The rendering pipeline supports multiple diagram types including architecture, workflow, sequence, dataflow, and lifecycle. Each command delegates to specific renderer modules located in renderers/<type>/render-<type>.mjs.

render

The render <type> <input.json> command compiles typed JSON IR into static HTML or SVG artifacts. Key options include:

• --quality standard|showcase – Controls rendering fidelity and detail level
• --repo-root <path> – Required for architecture diagrams to resolve relative paths

deliver

The deliver <type> <input.json> command executes a safety-first workflow that validates, renders, and atomically commits artifacts. According to the source code in archify/bin/archify.mjs, this command uses temporary staging directories and renameSync operations to prevent corruption of existing files.

• --open – Automatically opens the generated artifact in the default browser
• --json – Outputs machine-readable status information

preview

The preview <type> <input.json> command spawns a long-running Node process via archify/bin/preview.mjs that implements a live-reload development loop. The process watches the source file and re-renders only after the JSON passes all validation checks, preserving the last valid artifact during editing errors.

• --no-open – Suppresses automatic browser opening
• --quality and --repo-root – Standard rendering options

Validation and Inspection Commands

These commands leverage JSON-Schema definitions from archify/schemas/*.schema.json and standalone validators in renderers/shared/generated-validators.mjs.

validate

The validate <type> <input.json> command performs schema and layout validation without generating output files. Options include --json for structured output and --layout-json for detailed layout analysis.

inspect

The inspect <type> <input.json> command dumps a human-readable representation of the parsed intermediate representation, useful for debugging JSON structure issues.

check

The check <output.html> command executes the artifact verification script at archify/scripts/check-render-output.mjs, validating composition, routing, and rendering integrity of existing HTML files.

visual-check

The visual-check <output.html> command runs headless pixel-diff regression testing via archify/bin/visual-check.mjs to detect unintended visual changes between builds. Use --json for CI-friendly output.

Comparison and Migration Tools

compare architecture

The compare architecture <base.json> <head.json> command produces deterministic Before/Delta/After views using the delta engine at archify/delta/architecture-delta.mjs. This generates semantic diffs between architecture snapshots rather than simple text diffs.

• --receipt <path> – Saves comparison metadata to a JSON receipt file
• --json – Outputs structured comparison data

migrate workflow

The migrate workflow <old.json> <new.json> --to-schema 2 command converts workflow IR from legacy schema versions to current specifications, ensuring backward compatibility for archived diagrams.

Utility and Diagnostic Commands

guide

The guide [scenario] command provides interactive scenario assistance using data from archify/recipes/scenarios.mjs. It lists available recipes or queries specific architectural scenarios.

• --lang en|zh – Selects language for output (English or Chinese)
• --json – Returns structured recipe data

brands

The brands command group manages brand mark lookups and capture:

• brands [search] – Queries brand marks by name, alias, domain, or category
• brands capture <url> – Extracts brand metadata from websites using automated scraping

examples

The examples command renders all bundled demonstration diagrams located in archify/examples/, providing reference implementations for each supported diagram type.

doctor

The doctor command runs comprehensive health checks on the installation, verifying Node version compatibility, required file presence, and runtime binary accessibility.

demo

The demo [output-directory] command builds complete demonstration distributions including HTML, PNG, WebM, and social share cards for portfolio or documentation purposes.

CLI Implementation Architecture

The command definitions reside at lines 15-32 of archify/bin/archify.mjs, where a modular dispatch system routes arguments to specialized handlers. The architecture enforces deterministic output—renderers produce identical SVG/HTML given the same JSON IR, enabling reliable content hashing for receipts and cache validation.

Safety mechanisms include atomic file operations in deliver and compare commands, preventing partial writes during concurrent access. The extensible validator system allows new diagram types to inherit schema checking capabilities without modifying core CLI logic.

Command Usage Examples

Render an architecture diagram with showcase quality:

node archify/bin/archify.mjs render architecture web-app.architecture.json web-app.html --quality showcase

Compare two architecture snapshots and generate a JSON receipt:

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

Deliver a workflow diagram and open automatically:

node archify/bin/archify.mjs deliver workflow my-workflow.json workflow.html --open

Run the scenario guide in Chinese:

node archify/bin/archify.mjs guide --lang zh --json

Validate without rendering:

node archify/bin/archify.mjs validate architecture design.json --layout-json

Summary

• The Archify CLI exposes 15 commands through archify/bin/archify.mjs for complete diagram lifecycle management.
• Rendering commands (render, deliver, preview) delegate to type-specific modules and support standard or showcase quality profiles.
• Validation commands (validate, inspect, check, visual-check) leverage JSON-Schema validators and headless browser testing.
• Comparison tools use semantic diffing via archify/delta/architecture-delta.mjs to generate delta views between snapshots.
• Utility commands provide brand management, interactive guidance, installation diagnostics, and demo generation.
• All commands implement deterministic output and atomic file operations to ensure reliable CI/CD integration.

Frequently Asked Questions

How do I render a diagram from JSON using the Archify CLI?

Use the render command with the diagram type, input JSON, and output path. For example: node archify/bin/archify.mjs render architecture app.json output.html --quality showcase. The command compiles the typed JSON IR into HTML or SVG using the renderer defined in renderers/architecture/render-architecture.mjs.

What is the difference between the deliver and preview commands?

The deliver command performs a one-time atomic commit of a validated artifact, optionally opening it in the browser, while preview starts a persistent watch process via archify/bin/preview.mjs that re-renders only when the source JSON passes validation. Use deliver for production builds and preview for iterative development.

How does the compare command work for architecture reviews?

The compare architecture command accepts two JSON snapshots and generates a three-panel delta view (Before/Delta/After) using the engine in archify/delta/architecture-delta.mjs. It performs semantic differencing on the architecture graph rather than text comparison, producing deterministic HTML outputs suitable for code review workflows. The --receipt option saves comparison metadata for audit trails.

Where are the CLI command definitions located in the source code?

Command definitions and usage strings are located at lines 15-32 of archify/bin/archify.mjs. Individual command implementations are modularized across the codebase: renderers reside in renderers/<type>/render-<type>.mjs, validation uses renderers/shared/generated-validators.mjs, and specialized tools like visual-check and preview have dedicated binaries in archify/bin/.

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