How to Use the Archify CLI `guide` Command to Determine the Right Diagram Type

The archify guide command analyzes your scenario description and returns a deterministic recommendation for the optimal diagram type, complete with evidence requirements and a ready-to-use prompt.

The archify guide command powers Archify's question-first workflow, eliminating guesswork when selecting diagram styles. Instead of browsing dozens of diagram types, you describe what you need to visualize—Archify's recipe engine matches your scenario against eleven pre-defined recipes and returns a bounded, actionable recommendation. According to the tt-a1i/archify source code, this workflow is implemented across the CLI entry point, recipe scoring engine, and dual-output rendering system.

How the archify guide Command Works

The command follows a six-step pipeline that transforms natural language into structured diagram guidance.

Step 1: Parse the Scenario String

In archify/bin/archify.mjs, the CLI treats everything after guide as a free-form scenario description. This supports any text—from brief phrases to detailed questions.

archify guide "Show the flow of a user login with JWT and Redis cache miss"

The command definition in archify.mjs explicitly documents: archify guide [scenario or question] …

Step 2: Score Recipes Against Your Scenario

The scenario string routes to the recipe engine in archify/recipes/scenarios.mjs. Lines 308–309 codify the workflow philosophy: "Choose the question before the diagram type." The engine scores all eleven recipes against your input.

Step 3: Generate the Guide JSON

scripts/build-guide.mjs constructs a publicGuideData JSON object containing the top-scoring recipe. This structure includes:

• diagramType — the recommended visualization style
• evidence — mandatory elements to include
• avoid — elements that would dilute the diagram
• prompt — copy-ready command for rendering

Step 4: Render Interactive HTML (Default)

Without flags, Archify writes an interactive HTML page using scripts/guide-template.html. This template implements the Scenario Guide UI with question choosers and recipe browsing—saved to docs/guide.html in the published version.

Step 5: Output Machine-Readable JSON (--json)

Add --json to bypass HTML generation and print the recommendation to stdout. This enables CI pipelines, documentation generators, and chat-ops integrations.

Step 6: Localize Output (--lang)

The --lang en|zh flag forces UI or JSON field localization. Language handling lives in the guide template's localStorage and i18n string system.

Command-Line Examples

Basic Interactive Guide

Launches the Scenario Guide HTML page with your scenario pre-loaded:

archify guide "Show the flow of a user login with JWT and Redis cache miss"

JSON Output for Automation

Capture structured recommendations for downstream processing:

archify guide "Show the flow of a user login with JWT and Redis cache miss" --json > recommendation.json

Chinese Localization

Force Chinese UI rendering for international teams:

archify guide "展示带 JWT 鉴权、Redis 缓存未命中、数据库回避的登录流程" --lang zh

Consume JSON in Node.js Scripts

const rec = require("./recommendation.json");
console.log(`Suggested diagram: ${rec.recipe.diagramType}`);
console.log(`Must include: ${rec.recipe.evidence.join(", ")}`);
console.log(`Recommended command: ${rec.recipe.prompt}`);

Sample --json Output

{
  "scenario": "Show the flow of a user login with JWT and Redis cache miss",
  "recipe": {
    "diagramType": "sequence",
    "evidence": ["JWT auth", "Redis cache miss", "DB fallback"],
    "avoid": ["unrelated services"],
    "prompt": "archify render \"login-jwt-cache-miss\""
  }
}

Key Implementation Files

File	Purpose
archify/bin/archify.mjs	CLI entry point; defines guide command and flag parsing
archify/recipes/scenarios.mjs	Recipe library and scoring logic; contains usage hint at lines 308–309
scripts/build-guide.mjs	Generates publicGuideData JSON consumed by CLI and web UI
scripts/guide-template.html	Interactive Scenario Guide template with question chooser UI
docs/guide.html	Published guide page (built artifact)
archify/test/cli.test.mjs	Test coverage for CLI usage string display

Why the Question-First Approach Matters

• Eliminates diagram-type guessing — The CLI guides you from question → recipe → diagram in one command
• Ensures verifiable output — Each recipe lists mandatory evidence, keeping diagrams focused and reviewable
• Unifies CLI and web experiences — The same publicGuideData JSON powers both terminal and browser workflows
• Supports automation — The --json flag makes recommendations consumable by scripts, CI systems, and bots

Summary

• Run archify guide "[your scenario]" to get a deterministic diagram recommendation based on eleven curated recipes
• Use --json for machine-readable output suitable for CI pipelines and automation
• Apply --lang zh for Chinese-localized recommendations
• The recommendation includes diagramType, required evidence, elements to avoid, and a prompt for rendering
• All functionality is implemented across archify.mjs, scenarios.mjs, build-guide.mjs, and guide-template.html

Frequently Asked Questions

What diagram types can the guide command recommend?

The recipe engine in archify/recipes/scenarios.mjs scores against eleven pre-defined recipes. Output examples include sequence diagrams for auth flows with cache behaviors, or data-flow diagrams for product analytics pipelines. The exact type depends on your scenario's semantic match.

How does Archify decide which recipe matches my scenario?

The scoring algorithm evaluates your scenario string against each recipe's trigger conditions. The highest-scoring match becomes the recommendation. This logic is encapsulated in scenarios.mjs and exposed through build-guide.mjs's publicGuideData generation.

Can I use archify guide in CI/CD pipelines?

Yes—append --json to output structured JSON instead of HTML. Redirect to a file or pipe directly into downstream tools. The JSON schema includes scenario, recipe.diagramType, recipe.evidence, recipe.avoid, and recipe.prompt fields.

Where is the interactive Scenario Guide UI defined?

The HTML template lives in scripts/guide-template.html. It implements the question chooser interface and consumes the same publicGuideData JSON used by the CLI. The built version appears at docs/guide.html in the repository.

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