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

> Master Archify CLI commands render validate inspect check and doctor to generate HTML diagrams validate SVG output and audit your Node.js environment with ease.

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

---

**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](https://github.com/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`](https://github.com/tt-a1i/archify/blob/main/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.

```bash

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

```bash

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

```bash

# 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

```bash

# Validate an existing HTML artifact

archify check web-app.html

```

Sample JSON output:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html))
- Availability of standalone schema validators
- Existence of renderer files for all supported types

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.