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

> Master the Archify doctor command to run essential health checks. Ensure your Node.js runtime and critical template files are ready for diagram authoring with tt-a1i/archify.

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

---

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

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/checkout-platform.base.architecture.json) and [`checkout-platform.head.architecture.json`](https://github.com/tt-a1i/archify/blob/main/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:

```text
✔ 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:

```text
✖ 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.