Archify Preview Command Options: CLI Flags and Usage Guide

The archify preview command supports options for diagram type, input JSON, output HTML path, rendering quality (--quality), repository root for source evidence (--repo-root), and browser suppression (--no-open).

The archify CLI tool provides a live, loopback-only preview server for visualizing architecture diagrams from JSON source files. The preview command, implemented in the tt-a1i/archify repository, accepts several configuration flags that control rendering behavior, output destinations, and browser automation. Understanding these Archify preview command options allows developers to integrate diagram previews into local workflows and CI pipelines effectively.

Command Syntax and Structure

According to the CLI entry point in archify/bin/archify.mjs (lines 15-21), the preview sub-command follows this structure:

archify preview <type> <input> [output] [options]

The command expects a diagram type and input file path, with optional output destination and flags.

Available Preview Command Options

The preview implementation parses arguments between lines 94-105 of archify/bin/archify.mjs, supporting the following configuration options:

Required Arguments

• <type> – Specifies the diagram category. Valid values include architecture, workflow, sequence, dataflow, and lifecycle.
• <input> – Path to the typed JSON source file containing the diagram definition.

Optional Output Path

[output] – When provided, the generated HTML preview is saved to the specified file path. If omitted, the tool typically serves the preview without writing to disk or uses a default location.

Quality Flag

--quality <standard|showcase> – Controls the rendering quality profile. The default value is standard, while showcase enables higher-fidelity rendering suitable for presentations or documentation. This flag is processed alongside other global options in the CLI parser.

Repository Root Flag

--repo-root <path> – (Architecture diagrams only) Specifies the repository root directory for source-evidence lookup. This allows the preview to resolve file references and evidence links against the actual codebase location.

No-Open Flag

--no-open – Suppresses the automatic browser launch when the preview server starts. This option is essential for headless environments, CI/CD pipelines, or when you prefer to manually open the preview URL.

Usage Examples

The following examples demonstrate practical applications of the Archify preview command options:

Basic workflow preview with automatic browser opening:

archify preview workflow examples/agent-tool-call.workflow.json

Architecture preview with custom output path and high-quality rendering:

archify preview architecture examples/web-app.architecture.json /tmp/web-app.html --quality showcase

Headless preview for CI environments:

archify preview dataflow examples/dataflow-example.json --no-open

Architecture preview with repository root for source evidence:

archify preview architecture examples/mco-runtime.architecture.json --repo-root /path/to/mco-repo

Implementation Overview

The preview functionality is split across two key modules in the tt-a1i/archify codebase. The CLI entry point (archify/bin/archify.mjs) handles argument parsing and flag validation (lines 15-21 and 94-105), while the live preview runtime (archify/bin/preview.mjs) manages the actual HTTP server and browser orchestration. This separation allows the preview server logic to remain independent of CLI argument processing, making it easier to test and maintain.

Summary

• The archify preview command requires a diagram type and input JSON file, with optional output path and flags.
• Use --quality showcase for presentation-ready rendering, or standard for faster iteration.
• The --repo-root flag enables source-evidence resolution exclusively for architecture diagrams.
• Add --no-open to prevent automatic browser launching in automated environments.
• Configuration parsing occurs in archify/bin/archify.mjs, while the server runs from archify/bin/preview.mjs.

Frequently Asked Questions

What diagram types does the Archify preview command support?

The command accepts five diagram types: architecture, workflow, sequence, dataflow, and lifecycle. Each type corresponds to a specific JSON schema for diagram definition, and the preview server adjusts its rendering engine accordingly.

How do I prevent the browser from opening automatically when running a preview?

Include the --no-open flag in your command. This option is parsed by the CLI handler in archify/bin/archify.mjs and prevents the preview module from launching the default browser, making it ideal for Docker containers or CI pipelines.

Can I specify a custom output location for the generated HTML file?

Yes, provide the output path as the third positional argument after the input file. For example: archify preview architecture input.json /custom/path/output.html. If specified, the preview HTML is written to this location before the server starts.

What is the difference between standard and showcase quality modes?

The --quality flag accepts standard (default) or showcase. Standard mode prioritizes rendering speed for rapid iteration, while showcase mode enables higher-fidelity graphics and styling suitable for documentation, presentations, or stakeholder reviews.

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