How to Use the Archify Scenario Guide CLI to Select Diagram Types

Run node bin/archify.mjs guide "<scenario>" --json to return a JSON recipe that maps your design intent to the correct renderer (Architecture, Workflow, Sequence, Data-flow, or Lifecycle), then execute archify render with the provided prompt.

The Archify scenario guide CLI eliminates guesswork when choosing between diagram types by matching concrete design needs to pre‑validated scenario recipes. This tool is implemented as a zero‑dependency command in bin/archify.mjs and corresponds to the interactive web guide hosted at docs/guide.html. Whether you prefer terminal automation or a browser interface, the system narrows your requirements through an intent‑oriented questionnaire to guarantee the selected renderer supports your evidence contract.

Launching the Scenario Guide

You can access the scenario guide through two interfaces that share the same underlying logic defined in the repository.

Web Interface: Navigate to the generated page at https://tt-a1i.github.io/archify/guide.html or open the source file directly at docs/guide.html. This interactive page presents a questionnaire that filters scenario recipes based on your answers.

CLI Interface: For terminal workflows, invoke the guide logic directly from the repository root:

node bin/archify.mjs guide "service dependency map" --json

As documented in archify/SKILL.md, this command executes the same filtering logic as the web interface but returns structured data for automation pipelines.

Answering the Intent Questionnaire

Both interfaces present a short questionnaire designed to narrow the set of valid scenario recipes. The system asks intent‑oriented questions such as:

• "Do you need to model system boundaries?"
• "Are you visualising ordered events?"
• "Do you need to show data‑flow relationships?"

Each answer filters the available recipes stored in the repository's scenario definitions. According to the tt-a1i/archify source code, this logic maps you to a concrete scenario recipe rather than forcing you to manually choose between the five supported renderers: Architecture, Workflow, Sequence, Data-flow, or Lifecycle.

Retrieving the Scenario Recipe via CLI

Once you specify a scenario name, the CLI returns a JSON object containing everything needed to generate the diagram. The --json flag outputs a machine‑readable recipe with the recommended renderer, a ready‑to‑copy prompt, and metadata about the evidence contract.

# Query the guide for a specific scenario

node bin/archify.mjs guide "service dependency map" --json

The output follows this structure:

• renderer: The specific diagram type (e.g., "architecture")
• prompt: A copy‑paste ready command string for archify render
• scenario metadata: Description of the problem it solves and supported visual presets

This CLI behavior is implemented in bin/archify.mjs and documented in archify/SKILL.md.

Rendering the Selected Diagram

After retrieving the scenario recipe, pass the generated prompt to the appropriate Archify renderer. The guide guarantees compatibility between the scenario requirements and the renderer's capabilities.

# Render using the Architecture renderer as recommended by the guide

archify render --type architecture --input my-deps.json --output deps.svg

The --type parameter accepts the renderer name returned by the guide. The resulting diagram automatically applies the correct visual preset defined in the scenario recipe, ensuring it satisfies the evidence contract required by your design task.

How the Guide Logic Is Built

The scenario guide is not static HTML; it is generated from source data to ensure the web and CLI versions remain synchronized.

Key implementation files:

• docs/guide.html: The generated interactive scenario guide shown to users, built from scenario‑recipe JSON source.
• scripts/build-guide.mjs: The Node.js script that compiles guide.html from the scenario recipe definitions, ensuring the web interface reflects the latest CLI logic in bin/archify.mjs.
• archify/renderers/*/README.md: Documentation for each of the five typed renderers that the guide selects between.

When maintainers update scenario recipes or add new renderers, running scripts/build-guide.mjs regenerates docs/guide.html to match the CLI behavior.

Summary

• Launch the guide via the web at docs/guide.html or the CLI at bin/archify.mjs guide.
• Answer intent questions to filter scenario recipes based on your specific design problem (system boundaries, ordered events, or data‑flow relationships).
• Use --json with the CLI command to retrieve a machine‑readable recipe containing the recommended renderer and a ready‑to‑use prompt.
• Execute archify render --type <renderer> with the provided parameters to generate a diagram that automatically applies the correct visual preset.
• Reference scripts/build-guide.mjs to understand how the web guide stays synchronized with CLI logic.

Frequently Asked Questions

Can I use the Archify scenario guide without installing dependencies?

Yes. The CLI command node bin/archify.mjs guide operates with zero dependencies and requires only Node.js. The web guide at docs/guide.html runs entirely in the browser without any build step or server‑side processing.

What are the five diagram types the scenario guide can select?

The guide selects between Architecture, Workflow, Sequence, Data-flow, and Lifecycle renderers. Each corresponds to a subdirectory in archify/renderers/ with its own README.md documenting specific capabilities and evidence contracts.

How do I add a new scenario to the guide?

Add your scenario definition to the JSON source files processed by scripts/build-guide.mjs, then rebuild docs/guide.html. The CLI will automatically recognize the new scenario in bin/archify.mjs guide queries once the source data is updated.

What is the difference between using the web guide and the CLI guide?

The web guide at docs/guide.html provides an interactive questionnaire with clickable options, while the CLI at bin/archify.mjs guide accepts a scenario string argument and returns JSON output via the --json flag. Both interfaces execute the same filtering logic defined in the repository's scenario recipes.

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