# How to Use the Archify Guide Command for Interactive Scenario Exploration

> Explore architectural scenarios interactively with the Archify guide command. Discover the best diagram recipes for your unique architecture challenges using this bilingual question-first interface.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-04

---

**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:

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html)—replacing the placeholder `[[GUIDE_JSON]]`—to generate the static [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/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

```bash
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:

```bash
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:

```bash
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`:

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

```

You can extract specific fields:

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

```

### Generate Chinese-Language Output

To view scenario details in Chinese:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html), writing the result to [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) and writes a new [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/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.