How to Use the Archify Guide Command for Interactive Scenario Exploration

The Archify guide command provides a bilingual, question-first interface that helps you discover the optimal diagram recipe for your specific architecture problem by querying a curated catalogue of scenarios.

The archify guide command serves as the interactive entry point for the Archify CLI, a tool designed to translate natural language descriptions into architectural diagrams. By leveraging a structured scenario catalogue, this command enables developers to identify the precise diagramming recipe—complete with evidence requirements and constraints—best suited to their current problem context. Whether you are exploring available templates or targeting a specific workflow like "real-time checkout," the Archify guide command streamlines the discovery process through its query-driven interface.

Core Architecture and Execution Flow

When you invoke archify guide, the CLI executes a five-stage pipeline defined in archify/bin/archify.mjs. Understanding this flow helps you optimize your queries and understand the output format.

Option Parsing and Dispatch

The command begins by parsing arguments in the option loop located at lines 26-31 of archify/bin/archify.mjs. Here, the CLI accepts an optional free-form query string, the --json flag for raw output, and the --lang parameter for language selection. The dispatcher then routes control to the commandGuide function.

Catalogue Loading and Matching

Inside commandGuide, the system performs a dynamic import of the scenario catalogue at lines 51-57:

// Conceptual flow from archify/bin/archify.mjs
const scenarios = await import('archify/recipes/scenarios.mjs');

If you provide a query string, the command performs a case-insensitive substring match against the question field (or its Chinese equivalent) of each bounded-recipe object in the catalogue. The first matching scenario is selected for detailed display.

Output Generation Modes

The command operates in two primary output modes:

• List Mode: Invoked without a query, this displays a condensed list of all available scenario questions, useful for browsing the catalogue.
• Detail Mode: Triggered by supplying a query string, this renders the full recipe data including evidence requirements and constraints.

When --json is omitted, the command additionally triggers scripts/build-guide.mjs, which interpolates the scenario data into scripts/guide-template.html—replacing the placeholder [[GUIDE_JSON]]—to generate the static docs/guide.html file.

Scenario Recipe Data Model

Each entry in archify/recipes/scenarios.mjs follows a consistent schema designed to capture decision-making context:

• question: The natural-language prompt describing the architectural problem.
• type: The diagram mode (e.g., architecture, workflow).
• evidence: Minimum data required to render the diagram.
• when-not-to-use: Constraints that disqualify the recipe.
• prompt: A copy-ready CLI prompt you can feed back into Archify.

This structure ensures that the guide command returns actionable, context-aware recommendations rather than simple keyword matches.

Command Syntax and Language Options

The archify guide command supports both positional arguments and optional flags to control output format and localization.

Basic Syntax

archify guide [query] [--json] [--lang en|zh]

• query: Optional search string to filter scenarios.
• --json: Emits raw JSON to stdout instead of human-readable text or HTML.
• --lang: Switches between English (en) and Chinese (zh) field values before rendering.

Practical Usage Examples

The following commands demonstrate the primary workflows for interactive scenario exploration.

List All Available Scenarios

To browse the entire catalogue and discover what diagram types Archify supports:

archify guide

This outputs a numbered list of scenario questions to the terminal.

Query for a Specific Problem

To retrieve the detailed recipe for a checkout platform scenario:

archify guide "checkout platform delta"

The terminal displays the matched scenario's type, evidence requirements, constraints, and the ready-to-use prompt.

Export Recipe as JSON

For programmatic integration or piping to other tools like jq:

archify guide "checkout platform delta" --json > checkout-guide.json

You can extract specific fields:

archify guide "checkout platform delta" --json | jq '.prompt'

Generate Chinese-Language Output

To view scenario details in Chinese:

archify guide "checkout platform delta" --lang zh

Static HTML Report Generation

When running without the --json flag, the guide command produces a self-contained HTML document. The build process uses scripts/build-guide.mjs to inject the selected scenario's JSON payload into scripts/guide-template.html, writing the result to docs/guide.html.

This generated page replicates the terminal output but adds navigation styling and preserves the full context of the scenario guide for sharing or later reference. The template substitution targets the [[GUIDE_JSON]] placeholder with the serialized scenario object.

Summary

• The Archify guide command acts as a bilingual discovery interface for diagram recipes stored in archify/recipes/scenarios.mjs.
• It uses substring matching against scenario questions to identify relevant architectural patterns.
• Use --json for machine-readable output suitable for CI/CD pipelines, or omit it to generate a styled HTML guide at docs/guide.html.
• Language support (--lang en|zh) allows teams to consume documentation in their preferred language without maintaining separate catalogues.

Frequently Asked Questions

How does the Archify guide command determine which scenario to display?

The command performs a case-insensitive substring search through the question field of each scenario in archify/recipes/scenarios.mjs. It returns the first match where your query string appears within the scenario's question text (or its Chinese translation if --lang zh is specified). If no query is provided, it lists all available scenarios instead.

Can I use the Archify guide command in shell scripts or automation pipelines?

Yes. By appending the --json flag, the command outputs raw JSON to stdout, making it suitable for piping to tools like jq or parsing in Python scripts. This allows you to extract specific fields such as the prompt or evidence requirements for automated documentation workflows.

What files are modified when I run the guide command without --json?

Running archify guide without the JSON flag triggers scripts/build-guide.mjs, which reads scripts/guide-template.html and writes a new docs/guide.html file. This generated HTML file contains the interpolated scenario data and serves as a standalone reference document.

Does the guide command support languages other than English and Chinese?

Currently, the --lang flag only accepts en or zh parameters as implemented in archify/bin/archify.mjs. The scenario catalogue in archify/recipes/scenarios.mjs includes dedicated fields for both English and Chinese content, and the command swaps these values based on the flag before rendering output.

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