# How to Render an Architecture Diagram Directly Using the Archify CLI

> Easily render architecture diagrams with the Archify CLI. Convert JSON definitions to HTML with a single command for browser-ready visuals. Learn how now.

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

---

**The Archify CLI converts JSON architecture definitions into standalone HTML diagrams using Node.js, validating input against schemas and outputting browser-ready files with a single command.**

The tt-a1i/archify repository provides a lightweight command-line interface that lets you render an architecture diagram directly using the Archify CLI without external dependencies. Located in the `renderers` folder, this tool processes architecture JSON files through a synchronous pipeline that validates schemas, fetches brand assets, and generates self-contained HTML documents suitable for documentation or CI pipelines.

## CLI Rendering Pipeline

The rendering process follows four distinct stages defined in `archify/renderers/shared/cli.mjs` and `archify/renderers/architecture/render-architecture.mjs`:

### Loading and Validating the Diagram

The `loadDiagram` function (lines 19-38 in `archify/renderers/shared/cli.mjs`) ingests your JSON file—or defaults to [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) if no input is provided. It validates the structure against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) and prepares the HTML template for injection.

### Fetching Brand Assets

If your diagram specifies brand URLs, `loadDiagramWithBrandMarks` (lines 44-48) asynchronously retrieves these assets before rendering begins. This is the only asynchronous operation in the pipeline; all other steps execute synchronously to ensure script reliability.

### Generating SVG and Supporting Cards

The architecture-specific renderer in `archify/renderers/architecture/render-architecture.mjs` constructs the SVG visualization and assembles supplementary "cards" such as legends and notes. This module handles the graphical layout while delegating file operations to shared utilities.

### Writing the Final HTML

Finally, `writeDiagram` (lines 52-70) injects the rendered SVG and metadata into [`assets/template.html`](https://github.com/tt-a1i/archify/blob/main/assets/template.html), writing the completed file to your specified location or defaulting to [`architecture.html`](https://github.com/tt-a1i/archify/blob/main/architecture.html) in the working directory.

## Command-Line Usage

### Render the Built-in Example

To see the CLI in action without custom input, execute the renderer directly. This validates your installation and generates [`architecture.html`](https://github.com/tt-a1i/archify/blob/main/architecture.html) using the repository’s example diagram:

```bash
node archify/renderers/architecture/render-architecture.mjs

```

### Render a Custom Architecture Diagram

Pass your own JSON file to render an architecture diagram directly using the Archify CLI with custom data. Optionally specify an output filename to override the default:

```bash
node archify/renderers/architecture/render-architecture.mjs path/to/diagram.json custom-output.html

```

### CI/CD Pipeline Integration

Because the CLI is synchronous (excluding optional brand fetching), it integrates cleanly into automated workflows. Use it in shell scripts to generate documentation artifacts during builds:

```bash
#!/usr/bin/env bash
set -e
node archify/renderers/architecture/render-architecture.mjs "$CI_PROJECT_DIR/arch.json" "dist/architecture.html"

```

## Input Schema and Validation Requirements

All input files must conform to the architecture schema defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). The `loadDiagram` function enforces this validation at runtime, rejecting malformed JSON before rendering begins. Refer to [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) for a valid reference implementation.

## Summary

- The Archify CLI entry point is `archify/renderers/architecture/render-architecture.mjs`, leveraging shared utilities in `archify/renderers/shared/cli.mjs`.
- **Synchronous execution** makes the tool safe for CI/CD scripts, with only brand-mark fetching running asynchronously.
- The pipeline validates input against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), generates SVG cards, and injects them into [`assets/template.html`](https://github.com/tt-a1i/archify/blob/main/assets/template.html).
- Default output is [`architecture.html`](https://github.com/tt-a1i/archify/blob/main/architecture.html), but you can specify custom paths as command-line arguments.
- All diagram types (architecture, workflow, sequence, data-flow, lifecycle) use the same CLI structure in the `renderers` folder.

## Frequently Asked Questions

### What input format does the Archify CLI require?

The CLI requires JSON files that validate against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). The `loadDiagram` function automatically validates your input and falls back to [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) if no file is specified.

### Can I use the Archify CLI in automated build pipelines?

Yes. According to the tt-a1i/archify source code, the CLI operates synchronously except for optional brand-mark fetching, eliminating race conditions. This design makes it ideal for bash scripts and CI environments where deterministic output is required.

### How do I customize the output filename?

Provide a second command-line argument when invoking `render-architecture.mjs`. The `writeDiagram` function uses this parameter to determine the final HTML location, defaulting to [`architecture.html`](https://github.com/tt-a1i/archify/blob/main/architecture.html) if omitted.

### Does the CLI support diagram types other than architecture?

Yes. While this guide focuses on how to render an architecture diagram directly using the Archify CLI, the shared `cli.mjs` utilities support workflow, sequence, data-flow, and lifecycle diagrams through their respective renderer scripts in the `renderers` folder.