# How to Validate a Workflow Diagram with the Archify CLI Using the Showcase Quality Profile

> Validate workflow diagrams with the Archify CLI using the showcase quality profile. Ensure diagrams are ready for public presentation with strict checks. Learn how to use the command now.

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

---

**To validate a workflow diagram with the Archify CLI using the showcase quality profile, run `node archify/bin/archify.mjs validate workflow <file> --quality showcase` to enforce strict composition and readability checks that ensure the diagram is ready for public presentation.**

The Archify CLI from the `tt-a1i/archify` repository provides a validation pipeline for architecture diagrams defined in JSON IR format. When you **validate a workflow diagram with the Archify CLI**, appending the `--quality showcase` flag activates a restrictive rule-set that blocks publication unless the artifact meets presentation-grade standards for layout, reachability, and composition.

## What Defines the Showcase Quality Profile

The **showcase** quality profile applies a stricter rule-set than standard validation modes, requiring all nodes to be reachable, routes to clear legends, and the final artifact to pass strict composition checks. According to the source code in `archify/bin/archify.mjs`, invoking this profile triggers the `extractQualityArgs` function (lines 75-108) to set the environment variable `ARCHIFY_QUALITY_PROFILE=showcase`.

This environment variable signals the workflow renderer to enable high-severity validation rules that evaluate desktop-readability and visual composition. Unlike the default profile, **showcase** treats layout violations as fatal errors rather than warnings, ensuring the diagram renders correctly across different viewports before validation succeeds.

## The Validation Pipeline Explained

The CLI orchestrates validation through a five-stage pipeline implemented in the main driver and shared helpers:

### 1. Argument Parsing

The CLI entry point parses the command `validate workflow` alongside the input file path and quality flags. The `extractQualityArgs` helper in `archify/renderers/shared/cli.mjs` isolates the `--quality showcase` argument from the process arguments array.

### 2. Environment Setup

Before spawning the subprocess, the CLI constructs the `rendererEnv` object (lines 41-47 in `archify/bin/archify.mjs`), explicitly injecting `ARCHIFY_QUALITY_PROFILE=showcase` into the environment. This ensures the workflow renderer inherits the correct validation mode regardless of the parent shell’s configuration.

### 3. Renderer Execution

The CLI resolves the workflow renderer path via `rendererPath('workflow')` and spawns the process at `archify/renderers/workflow/render-workflow.mjs`. The renderer loads the input JSON IR and executes both the schema validator and the layout engine against the showcase criteria.

### 4. Diagnostics Collection

If the renderer encounters a violation, it exits with a non-zero status. The `rendererFailure` handler (lines 78-90 in `archify/bin/archify.mjs`) intercepts the exit code and harvests structured diagnostics from the subprocess stderr, normalizing them for CLI output.

### 5. Receipt Generation

When the `--json` flag is present, the CLI invokes `reportValidateFailure` (lines 84-85) to emit a machine-readable receipt. This JSON object contains the validation status, check counts, specific error codes, and an array of `supportedFixes` for any failed rules.

## Running the Validation Command

First, install the CLI globally using the package manager:

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

```

Prepare your workflow diagram as a JSON file following the Archify IR schema. The repository includes a sample at [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json) for testing.

Execute validation with the showcase profile and JSON output:

```bash
node archify/bin/archify.mjs validate workflow \
  examples/agent-tool-call.workflow.json \
  --quality showcase \
  --json

```

### Successful Validation Output

When all 12 checks pass, the CLI returns a receipt confirming compliance:

```json
{
  "schemaVersion": 1,
  "ok": true,
  "command": "validate",
  "stage": "validate",
  "type": "workflow",
  "input": "examples/agent-tool-call.workflow.json",
  "error": null,
  "diagnostics": [],
  "validation": {
    "checksPassed": 12,
    "checkCount": 12,
    "compositionProfile": "signal-flow",
    "compositionStatus": "pass"
  }
}

```

### Handling Validation Failures

If the diagram violates showcase rules—such as failing desktop-readability standards—the CLI returns a detailed error payload:

```json
{
  "ok": false,
  "command": "validate",
  "stage": "validate",
  "type": "workflow",
  "input": "examples/agent-tool-call.workflow.json",
  "error": "Final artifact failed composition/desktop-readability.",
  "diagnostics": [
    {
      "code": "artifact/composition/desktop-readability",
      "severity": "error",
      "message": "Final artifact failed composition/desktop-readability.",
      "subject": { "check": "composition/desktop-readability" },
      "evidence": { "details": [] },
      "supportedFixes": [
        "reduce the viewBox width, shorten node copy, widen affected nodes, or split the diagram"
      ]
    }
  ]
}

```

## Interpreting Error Codes and Fixes

The **showcase** profile enforces specific error codes like `artifact/composition/desktop-readability`. Each diagnostic object includes a `supportedFixes` array containing actionable remediation strategies. The test suite in `archify/test/cli-output-types.test.mjs` asserts that these fields are present for all validation failures, ensuring the CLI remains consistent across versions.

When you encounter a composition error, apply one of the suggested fixes—such as reducing the viewBox width or splitting the diagram—and rerun the validation command until the `compositionStatus` returns `pass`.

## Summary

- The **showcase** quality profile sets `ARCHIFY_QUALITY_PROFILE=showcase` via `extractQualityArgs` in `archify/bin/archify.mjs` to enable strict validation rules.
- The validation pipeline parses arguments, configures the `rendererEnv`, executes the workflow renderer at `archify/renderers/workflow/render-workflow.mjs`, and collects diagnostics via `rendererFailure`.
- Use `node archify/bin/archify.mjs validate workflow <file> --quality showcase --json` to generate machine-readable receipts with detailed check results.
- Failed checks return specific error codes (e.g., `artifact/composition/desktop-readability`) with remediation guidance in the `supportedFixes` field.

## Frequently Asked Questions

### What is the difference between the default quality profile and the showcase profile in Archify?

The default profile performs basic schema validation and layout checks, while the **showcase** profile enforces stricter composition rules through the `ARCHIFY_QUALITY_PROFILE=showcase` environment variable. It requires all nodes to be reachable, routes to clear legends, and artifacts to meet desktop-readability standards before validation succeeds.

### How do I fix a desktop-readability error when validating with the showcase profile?

When you encounter the `artifact/composition/desktop-readability` error code, apply one of the `supportedFixes` suggested in the JSON output: reduce the viewBox width, shorten node copy text, widen affected nodes, or split the diagram into multiple smaller diagrams. Rerun the validation command after adjustments to verify the fix.

### Can I validate workflow diagrams without installing Archify globally?

Yes, you can run the CLI directly using `node` pointing to the local binary path. The command `node archify/bin/archify.mjs validate workflow <file> --quality showcase` works regardless of global installation status, provided the repository dependencies are available in `node_modules`.

### Where does the Archify CLI store the validation rules for the showcase profile?

The showcase rules are implemented in the workflow renderer at `archify/renderers/workflow/render-workflow.mjs`, which checks the `ARCHIFY_QUALITY_PROFILE` environment variable set by the CLI driver in `archify/bin/archify.mjs`. The specific schema and layout constraints are enforced by the renderer's validation engine when the environment variable equals `showcase`, as verified by the test suite in `archify/test/cli-output-types.test.mjs`.