How to Use the Archify Doctor Command: Installation Health Checks Explained

The archify doctor command performs a built-in health check that verifies your Node.js runtime is at least version 18 and confirms the presence of critical template files, rendering scripts, and runtime dependencies required for diagram authoring.

The doctor sub-command is a diagnostic tool included in the tt-a1i/archify repository that validates your local environment before you begin rendering or comparing architecture diagrams. According to the source code in archify/bin/archify.mjs, this command systematically inspects nine distinct components to ensure the toolchain is ready for use. You can invoke it directly via Node.js or through the package binary if installed globally.

Running the Archify Doctor Command

Execute the health check from the repository root using the entry-point script:

node bin/archify.mjs doctor

If you have installed the package globally or added the local bin directory to your PATH, you can use the shorthand:

archify doctor

What the Archify Doctor Command Validates

The commandDoctor() function, starting at line 91 in archify/bin/archify.mjs, initializes a checks array and populates it with nine specific validation routines. Each check returns a labeled result with a boolean ok flag and descriptive text.

Node.js Runtime Verification

The first check parses process.versions.node to extract the major version number:

• Requirement: Node.js ≥ 18 (required for modern ES-modules support)
• Implementation: Lines 93-99 compare the major version against the minimum threshold
• Output format: Node.js v18.17.0 (requires >=18)

If your runtime is below version 18, the check fails with the label "unsupported".

Core Asset and File Presence Checks

The remaining eight validations verify that specific files exist in the expected directory structure:

1. Core template (assets/template.html) — Confirms the HTML scaffold used for all rendered diagrams exists (lines 101-107).

2. Example renderer (scripts/render-examples.mjs) — Validates the built-in example rendering script is present (lines 108-114).

3. Live-preview runtime (bin/preview.mjs) — Checks for the browser-based viewer component (lines 115-121).

4. Visual-check runtime (bin/visual-check.mjs) — Ensures the automated browser validation tool is available (lines 122-128).

5. Output-path safety helper (renderers/shared/output-path.mjs) — Verifies the utility that safely resolves output file paths (lines 129-135).

6. Scenario guide (recipes/scenarios.mjs) — Confirms the scenario definitions used by the guide command exist (lines 136-142).

7. Authoring reference docs (references/*.md) — Checks for three markdown reference files in the references/ directory (lines 143-151).

8. Architecture-compare runtime and fixtures — Validates delta/architecture-delta.mjs and two JSON fixture files (checkout-platform.base.architecture.json and checkout-platform.head.architecture.json) used by the compare command (lines 152-162).

Understanding Archify Doctor Command Output

The final reporting logic iterates over the checks array at lines 163-170 in archify/bin/archify.mjs, printing each result with a ✅ (pass) or ❌ (fail) symbol.

Successful Validation

When every check passes, you will see output similar to:

✔ Node.js v18.17.0 (requires >=18)
✔ Core template
✔ Example renderer
✔ Live preview runtime
✔ Visual-check runtime
✔ Output path safety runtime
✔ Scenario guide
✔ Progressive authoring references
✔ Architecture compare runtime and proof fixtures

Archify is ready.

Failed Checks

If validation fails—for example, with an unsupported Node.js version—the output highlights the specific failure:

✖ Node.js v16.14.0 (requires >=18)   ← unsupported
✔ Core template
...

The CLI lists only the failing items with their status labels, allowing you to quickly identify missing dependencies or configuration issues.

Advanced Implementation Details

While commandDoctor() primarily prints diagnostic output to the console, the underlying implementation reveals a programmatic structure that populates a checks array. The function is defined as an async operation, allowing for potential future async validations.

If you need to integrate these checks into a custom script, you could reference the file-existence verification patterns found in lines 101-162 of archify/bin/archify.mjs. These patterns typically wrap fs checks in labeled objects containing the ok boolean and descriptive label strings.

Summary

• The Archify doctor command validates nine critical components, from Node.js version compatibility to the presence of template and runtime files.
• Node.js 18 or higher is strictly required for ES-modules support, verified by parsing process.versions.node.
• File path checks cover assets/template.html, bin/preview.mjs, bin/visual-check.mjs, scripts/render-examples.mjs, and supporting utilities in renderers/shared/ and delta/.
• Invocation is via node bin/archify.mjs doctor or the archify doctor shorthand for global installs.
• Success criteria: All nine checks return ok: true, triggering the "Archify is ready." confirmation message.

Frequently Asked Questions

What Node.js version is required to run Archify?

Archify requires Node.js version 18 or higher. The doctor command explicitly checks process.versions.node and extracts the major version number; if it detects version 16 or earlier, it marks the check as "unsupported" and the overall validation fails.

Can I use the doctor command programmatically in my own scripts?

The commandDoctor() function in archify/bin/archify.mjs is designed primarily for CLI output, printing results directly to the console. While it does not return the checks array for external consumption, you can reference the implementation pattern—creating labeled check objects with ok boolean flags—to build similar diagnostic logic in your own Node.js applications.

What should I do if the doctor command reports missing files?

If the doctor output shows ❌ symbols for any core assets (such as assets/template.html or bin/preview.mjs), verify that you have cloned the tt-a1i/archify repository completely and that your working directory matches the expected structure. Missing files typically indicate an incomplete installation or that you are running the command from outside the project root.

Is the doctor command mandatory before running other Archify commands?

While not strictly enforced, running archify doctor is strongly recommended before authoring or rendering diagrams. The command ensures that critical dependencies like the HTML template and rendering scripts are present, preventing runtime errors during the diagram generation process.

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