# Archify CLI Commands: Complete Command-Line Interface Reference

> Explore Archify CLI commands for creating and managing architecture diagrams. Discover 11 core commands like render, compare, and validate in this comprehensive reference.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-08-07

---

**Archify provides 11 core CLI commands (`render`, `compare`, `deliver`, `preview`, `validate`, `inspect`, `check`, `guide`, `examples`, `doctor`, `demo`) for creating, validating, and managing architecture diagrams from JSON specifications.**

The **Archify CLI** transforms JSON architecture specifications into interactive HTML diagrams, enables change-impact analysis, and automates CI verification workflows. All command parsing and dispatch logic lives in the main entry point [`archify/bin/archify.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs).

## Essential Archify CLI Commands

### Render Diagrams with `archify render`

The `render` command is the primary workhorse for generating artifacts. It accepts a diagram type, input JSON, and optional output path.

```bash
archify render <type> <input.json> [output.html] [--quality standard|showcase] [--repo-root path]

```

Supported **diagram types** include `architecture`, `workflow`, `sequence`, `dataflow`, and `lifecycle`. The optional `--quality` flag toggles between standard styling and showcase-quality presentation. Repository-aware rendering activates when `--repo-root` points to a source directory, enabling deeper cross-references for architecture diagrams.

Example usage:

```bash
archify render architecture examples/web-app.architecture.json output.html

```

### Compare Versions with `archify compare`

Track architectural evolution using the `compare` command, implemented in [`archify/delta/architecture-delta.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/delta/architecture-delta.mjs).

```bash
archify compare architecture <base.json> <head.json> [output.html] [--receipt path] [--json] [--quality standard|showcase] [--repo-root path]

```

This command performs **canonicalization and delta calculation** between JSON specifications, emitting both an HTML diff visualization and an optional machine-readable receipt. The `--json` flag enables programmatic consumption for CI pipelines.

Example with receipt generation:

```bash
archify compare architecture base.json head.json diff.html --receipt diff.receipt.json --json

```

### Deliver Verified Artifacts with `archify deliver`

The `deliver` command wraps rendering with **final artifact verification** before persistence.

```bash
archify deliver <type> <input.json> [output.html] [--json] [--open] [--quality standard|showcase] [--repo-root path]

```

The `--open` flag automatically launches the generated HTML in the default browser. Under the hood, deliver invokes [`archify/scripts/check-render-output.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/scripts/check-render-output.mjs) to validate composition, routing, and SVG validity.

### Live Preview with `archify preview`

Iterate interactively using the preview server with file watching.

```bash
archify preview <type> <input.json> [output.html] [--no-open] [--quality standard|showcase] [--repo-root path]

```

The preview command starts a **live-reload development server** that monitors the source JSON and regenerates the view on changes. Use `--no-open` when running in containerized environments.

```bash
archify preview dataflow dataflow-example.json --no-open

```

## Validation and Debugging Commands

### Validate Specifications with `archify validate`

Catch schema and input errors early without producing artifacts.

```bash
archify validate <type> <input.json> [--json] [--layout-json] [--quality standard|showcase] [--repo-root path]

```

The `--layout-json` option emits the **internal layout description** for debugging rendering issues. This command uses the same validation path as `render` and `deliver` but skips HTML generation.

```bash
archify validate architecture invalid-arch.json --json

```

### Inspect Specifications with `archify inspect`

Quickly introspect a specification without rendering overhead.

```bash
archify inspect <type> <input.json>

```

This prints a **human-readable summary** of the parsed JSON structure, useful for debugging malformed inputs or understanding third-party specifications.

### Verify Existing Artifacts with `archify check`

Validate previously generated HTML files in CI pipelines.

```bash
archify check <output.html>

```

This command runs the **final artifact checker** standalone, verifying that composition, routing, and SVG validity constraints are satisfied. Implementation resides in [`archify/scripts/check-render-output.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/scripts/check-render-output.mjs).

## Utility and Onboarding Commands

### Interactive Guides with `archify guide`

Query the built-in scenario database for recommendations.

```bash
archify guide [scenario|question] [--json] [--lang en|zh]

```

The guide command sources data from [`archify/recipes/scenarios.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/recipes/scenarios.mjs), supporting **multilingual help** (English and Chinese) and structured JSON output for tooling integration.

```bash
archify guide --json

```

### Explore Examples with `archify examples`

Render all **bundled example diagrams** from [`archify/examples/`](https://github.com/tt-a1i/archify/tree/main/archify/examples):

```bash
archify examples

```

This demonstrates the full range of supported diagram types and serves as regression testing material.

### Environment Diagnostics with `archify doctor`

Verify installation completeness before first use.

```bash
archify doctor

```

The doctor command runs a **self-diagnostic** checking Node version compatibility, core template presence, renderer availability, and other runtime dependencies.

### Generate Starter Demo with `archify demo`

Create a ready-to-open preview for new users.

```bash
archify demo [output-directory]

```

This generates a **starter demo HTML** using the bundled web-app example, providing immediate visual feedback on a working Archify installation.

## Command Implementation Architecture

Each CLI command maps to a dedicated handler function in [`archify/bin/archify.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs):

- `commandRender` — handles `render`
- `commandCompare` — handles `compare`
- `commandDeliver` — handles `deliver`
- `commandPreview` — handles `preview`
- `commandValidate` — handles `validate`
- `commandInspect` — handles `inspect`
- `commandCheck` — handles `check`
- `commandGuide` — handles `guide`
- `commandExamples` — handles `examples`
- `commandDoctor` — handles `doctor`
- `commandDemo` — handles `demo`

Shared argument extraction utilities (`extractQualityArgs`, `extractRepoRootArgs`) normalize common flags across commands. Type-specific rendering delegates to modules under `archify/renderers/<type>/render‑<type>.mjs`.

## Quality and Repository Flags

Most rendering commands accept these standard options:

| Flag | Values | Purpose |
|------|--------|---------|
| `--quality` | `standard` (default), `showcase` | Controls visual polish and presentation assets |
| `--repo-root` | filesystem path | Enables repository-aware rendering with source cross-references |
| `--json` | flag | Emit structured output for programmatic consumption |
| `--open` / `--no-open` | flag | Control automatic browser launch |

## Summary

- **Core rendering**: `render`, `deliver`, and `preview` produce HTML artifacts with varying verification and interactivity levels
- **Change analysis**: `compare` generates deltas between architecture versions with optional receipt files
- **Quality assurance**: `validate`, `inspect`, and `check` verify specifications and artifacts without full rendering
- **Onboarding support**: `guide`, `examples`, `doctor`, and `demo` accelerate first-time setup and discovery
- **Entry point**: All commands dispatch through `archify/bin/archify.mjs` with shared argument parsing and error handling

## Frequently Asked Questions

### What file formats does Archify CLI accept as input?

Archify CLI accepts **JSON specification files** defined by the Archify schema. Each diagram type (`architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`) has specific structural requirements. The `validate` command checks schema compliance without generating output.

### How do I integrate Archify into a CI pipeline?

Use `archify validate` to catch errors during build stages, `archify compare` with `--json` to verify architectural changes in pull requests, and `archify check` to validate pre-built artifacts before deployment. The `--json` flag on applicable commands outputs machine-readable status for scripted workflows.

### Where is the CLI entry point located?

The main CLI entry point is [`archify/bin/archify.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs), which defines the `usage()` function and dispatches to command-specific handlers like `commandRender` and `commandCompare`. Individual renderers live under `archify/renderers/<type>/render‑<type>.mjs`.

### Does Archify support multiple languages for documentation?

Yes. The `archify guide` command supports **English (`en`) and Chinese (`zh`)** through the `--lang` flag, sourcing content from [`archify/recipes/scenarios.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/recipes/scenarios.mjs).