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

> Learn to use the Archify CLI guide command to get a deterministic recommendation for the optimal diagram type, including evidence and prompts. Simplify your diagramming process.

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

---

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html). This template implements the *Scenario Guide* UI with question choosers and recipe browsing—saved to [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/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:

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

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

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

```

### Consume JSON in Node.js Scripts

```javascript
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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) | Interactive Scenario Guide template with question chooser UI |
| [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/docs/guide.html) in the repository.