Archify CLI Commands: Complete Command-Line Interface Reference

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.

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.

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:

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.

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:

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.

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 to validate composition, routing, and SVG validity.

Live Preview with archify preview

Iterate interactively using the preview server with file watching.

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.

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.

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.

archify validate architecture invalid-arch.json --json

Inspect Specifications with archify inspect

Quickly introspect a specification without rendering overhead.

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.

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.

Utility and Onboarding Commands

Interactive Guides with archify guide

Query the built-in scenario database for recommendations.

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

The guide command sources data from archify/recipes/scenarios.mjs, supporting multilingual help (English and Chinese) and structured JSON output for tooling integration.

archify guide --json

Explore Examples with archify examples

Render all bundled example diagrams from archify/examples/:

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.

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.

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:

• 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}