# How to Validate a Workflow Diagram with the Archify CLI: A Complete Guide

> Validate workflow diagrams with the Archify CLI. Ensure your workflow JSON is valid against the schema and renderer specifications. Learn how to use the Archify CLI validate command now.

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

---

**The Archify CLI provides a built-in `validate` command that checks workflow JSON files against the official schema and runs renderer-specific validation, exiting with status 0 on success or printing detailed error paths on failure.**

The Archify CLI from the `tt-a1i/archify` repository includes a robust validation system for workflow diagrams. You can validate your workflow JSON files before rendering to catch schema errors, missing properties, or invalid references. This guide covers how to use the `validate` command with practical examples and source code references.

## Understanding the Validation Pipeline

The validation process in `archify/bin/archify.mjs` performs three distinct checks:

- **Schema validation** using the compiled AJV validator located in `archify/renderers/shared/generated-validators.mjs`
- **Renderer-specific validation** via the `validateWorkflow()` function in `archify/renderers/workflow/render-workflow.mjs`
- **Temporary-directory hygiene** to ensure isolated execution without leaving artifacts behind

## Prerequisites and Setup

No additional Node modules are required. The bundled validators ship with the skill. Install Archify globally via:

```bash
npx skills add tt-a1i/archify -g

```

## Validating a Workflow Diagram

### Prepare Your Workflow JSON

Create a file following the schema defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json):

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Login flow" },
  "lanes": [
    { "id": "browser", "label": "Browser" },
    { "id": "api", "label": "API" }
  ],
  "nodes": [
    { "id": "login", "label": "Login", "lane": "browser" },
    { "id": "validate", "label": "Validate JWT", "lane": "api" }
  ],
  "edges": [
    { "from": "login", "to": "validate" }
  ],
  "mainPath": ["login", "validate"]
}

```

### Run the Validate Command

Execute the validator from your terminal:

```bash
node archify/bin/archify.mjs validate workflow workflow.json

```

Add `--json` for machine-readable output suitable for CI pipelines:

```bash
node archify/bin/archify.mjs validate workflow workflow.json --json > report.json

```

Add `--layout-json` to include computed layout information:

```bash
node archify/bin/archify.mjs validate workflow workflow.json --layout-json > layout.json

```

### Interpret the Results

A successful validation exits with status 0 and prints:

```

✔ workflow.json is valid

```

Failed validation provides specific error paths pointing to the offending property:

```

✖ workflow.json schema validation failed:
  /lanes/0/id: must match pattern "^[a-zA-Z][a-zA-Z0-9_-]*$"

```

## How Validation Works Under the Hood

According to the source code in `tt-a1i/archify`, the validation process:

1. **Dispatches to the AJV validator** through `archify/renderers/shared/validator.mjs`, which uses the compiled schemas in `generated-validators.mjs`
2. **Executes renderer validation** by calling `validateWorkflow()` in `archify/renderers/workflow/render-workflow.mjs` (lines 95-99)
3. **Runs in isolation** using a temporary directory that gets cleaned up automatically (lines 202-209)

## Summary

- The **Archify CLI** provides built-in workflow validation via the `validate` command
- Validation checks **schema compliance**, **renderer requirements**, and **file hygiene**
- Use **`--json`** for CI-friendly machine-readable output
- Use **`--layout-json`** to preview computed layout data
- The **AJV validator** in `generated-validators.mjs` handles schema validation against [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)
- **Exit code 0** indicates success; errors include precise JSON paths to invalid properties

## Frequently Asked Questions

### What exit code does the Archify CLI return on validation failure?

The CLI returns a non-zero exit status when validation fails. A **status 0** indicates the workflow JSON is valid according to both the schema and renderer requirements.

### Can I validate workflow diagrams without installing additional dependencies?

Yes. The validation system is **self-contained** and ships with the bundled AJV validators in `archify/renderers/shared/generated-validators.mjs`. No extra Node modules are required beyond the core Archify installation.

### How do I interpret schema validation errors?

Error messages include the **JSON path** to the offending property, such as `/lanes/0/id: must match pattern "^[a-zA-Z][a-zA-Z0-9_-]*$"`. This indicates the first lane's ID violates the naming convention and must start with a letter followed by alphanumeric characters, underscores, or hyphens.

### Where can I find the official workflow schema definition?

The canonical schema resides at [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) in the repository. This file defines required properties including `schema_version`, `diagram_type`, `lanes`, `nodes`, and `edges`.