How to Use Archify CLI Commands: render, validate, inspect, check, and doctor

Archify CLI provides five core commands—render, validate, inspect, check, and doctor—that generate self‑contained HTML diagrams from JSON IR, validate SVG output quality, and audit your Node.js environment via the dispatcher in archify/bin/archify.mjs.

The archify package in the tt‑a1i/archify repository ships as a self‑contained Node.js CLI. It drives a family of diagram renderers (architecture, workflow, sequence, data‑flow, and lifecycle) through a lightweight command dispatcher that spawns isolated renderer processes and optionally runs a post‑render artifact checker.

Archify CLI Command Overview

The command dispatcher lives in archify/bin/archify.mjs. It parses the sub‑command, locates the appropriate renderer using rendererPath(type) (lines 34‑38), and spawns a new Node process via runNode to execute the heavy lifting. All commands propagate exit codes back to the shell, making them suitable for CI pipelines.

The CLI supports five primary sub‑commands:

• render – Generates a self‑contained HTML diagram from JSON input.
• validate – Renders to a temporary file, runs the artifact checker, and returns structured results.
• inspect – Shortcut for validate … --layout-json; emits the computed layout for architecture diagrams.
• check – Executes the post‑render checker on an existing HTML file.
• doctor – Performs environment sanity checks (Node ≥ 18, templates, validators).

Generating Diagrams with archify render

The render command is the primary entry point for diagram generation. It accepts a diagram type, a JSON intermediate representation (IR) file, and an optional output path.

Supported Diagram Types

As defined in the CLI dispatcher, valid types are:

• architecture
• workflow
• sequence
• dataflow
• lifecycle

Each type maps to a dedicated renderer module under archify/renderers/<type>/render-<type>.mjs. For example, architecture diagrams are processed by archify/renderers/architecture/render-architecture.mjs.

Usage and Output

The renderer validates the JSON against archify/schemas/<type>.schema.json, computes the layout, and injects the resulting SVG into archify/assets/template.html. The final HTML includes a built‑in export menu supporting PNG, JPEG, WebP, and SVG at up to 4× native resolution.

# Render an architecture diagram to web-app.html

archify render architecture examples/web-app.architecture.json web-app.html

If you omit the output path, the CLI writes to a default filename based on the input.

Validating Diagram Output

Validation ensures that generated diagrams meet quality standards (finite numeric values, orthogonal arrows, clearance from legends) before they reach production.

The validate Command

commandValidate (lines 73‑94 in archify/bin/archify.mjs) performs a full render cycle to a temporary file, then executes scripts/check-render-output.mjs to inspect the SVG. It returns a structured JSON result and prints a human‑readable summary.

# Validate a workflow diagram

archify validate workflow examples/agent-tool-call.workflow.json

Output example:

ok workflow /path/to/examples/agent-tool-call.workflow.json (23 checks)

Use the --json flag to capture machine‑readable output, or --layout-json to emit the computed layout coordinates (useful for architecture diagrams).

The inspect Command

inspect is a convenience alias that invokes commandValidate with the --layout-json flag (see line 46). It is the fastest way to extract layout metadata without writing a full HTML file.

# Extract layout JSON for an architecture diagram

archify inspect architecture examples/web-app.architecture.json > layout.json

Auditing Existing Artifacts with archify check

The check command runs the post‑render artifact checker against a previously generated HTML file. This is useful in CI workflows where the render step and validation step are decoupled.

commandCheck (lines 61‑66) spawns scripts/check-render-output.mjs, which verifies:

• Presence of a single <svg> element
• Finite numeric values in all coordinates
• Orthogonal arrow paths
• Proper clearance from the diagram legend

# Validate an existing HTML artifact

archify check web-app.html

Sample JSON output:

{
  "ok": true,
  "file": "/full/path/web-app.html",
  "checks": [ … ]
}

Environment Diagnostics with archify doctor

The doctor command performs a sanity check of your local environment. As implemented in archify/bin/archify.mjs, it verifies:

• Node.js version ≥ 18
• Presence of the core HTML template (archify/assets/template.html)
• Availability of standalone schema validators
• Existence of renderer files for all supported types

# Run system health check

archify doctor

Example output:

[ok] Node.js v18.14.0 (requires >=18)
[ok] Core template
[ok] Standalone schema validators
…
Archify is ready.

How the Rendering Pipeline Works

Understanding the internal flow helps debug complex diagrams:

1. JSON IR – You provide a typed JSON description (e.g., examples/web-app.architecture.json).
2. Renderer Spawning – The CLI locates the renderer with rendererPath(type) and spawns it via runNode, isolating rendering work from the CLI wrapper.
3. Schema Validation – The renderer validates input against archify/schemas/<type>.schema.json.
4. SVG Construction – The renderer builds an SVG and embeds it inside archify/assets/template.html.
5. Artifact Check – For validate and check commands, scripts/check-render-output.mjs audits the SVG for rendering artifacts.
6. Export – The final HTML page includes JavaScript to copy PNG to the clipboard or download raster/vector formats.

Summary

• The Archify CLI is the entry point at archify/bin/archify.mjs, dispatching commands to isolated renderer processes.
• Use render to generate standalone HTML diagrams from JSON IR for five diagram types.
• Use validate to perform a full render‑and‑check cycle, or inspect to quickly extract layout JSON.
• Use check to audit existing HTML files against the SVG quality rules defined in scripts/check-render-output.mjs.
• Use doctor to verify Node ≥ 18 and the integrity of templates, schemas, and renderers before running other commands.

Frequently Asked Questions

What Node.js version does Archify CLI require?

Archify requires Node.js version 18 or higher. The doctor command explicitly checks this and will report [fail] if your runtime is older, as the renderer modules rely on modern Node APIs for file handling and subprocess spawning.

What is the difference between validate and inspect?

validate performs a full render to a temporary file and runs the complete artifact checker, optionally returning structured JSON or layout data via flags. inspect is a convenience wrapper that calls validate with --layout-json automatically, making it the shortest path to retrieve computed node coordinates for architecture diagrams without generating HTML.

How does the post‑render checker work?

The check command invokes scripts/check-render-output.mjs, which parses the generated HTML, extracts the embedded SVG, and runs a series of assertions (e.g., addCheck calls around lines 32‑58) verifying SVG validity, numeric precision, and visual layout rules such as orthogonal edges and legend clearance.

Can I validate a diagram without writing an HTML file?

Yes. The validate command writes to a temporary file internally and deletes it after checking. If you only need the validation result or the layout JSON, use validate … --json or inspect, neither of which persist the HTML artifact to your working directory.

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