# How to Use the Archify CLI `doctor` Command: Complete Health-Check Guide

> Learn to use the Archify CLI doctor command for a complete installation health-check. Ensure your Archify setup is ready before running other commands.

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

---

**The `archify doctor` command validates that your Archify CLI installation meets all runtime requirements before you run any other commands.**

The `doctor` command is a built‑in diagnostic tool in the Archify CLI from `tt-a1i/archify`. It performs a comprehensive health check on your environment, catching configuration issues early so you avoid cryptic failures later. This guide covers how to use the Archify CLI `doctor` command, what checks it performs, and how to interpret its output.

## What the Archify Doctor Command Checks

When you run `archify doctor`, it executes four validation layers:

1. **Node.js version** — confirms you're running Node 18 or newer
2. **Required package files** — verifies all validator modules are present in your installation
3. **Output-path safety** — ensures the default output directory is writable and won't overwrite existing data
4. **Validator integrity** — loads each validator with a special `?doctor=` query parameter to confirm clean execution

In `archify/bin/archify.mjs`, the `doctor` subcommand delegates to `commandDoctor()` at line 1997:

```javascript
case 'doctor': await commandDoctor();

```

## How to Run the Archify Doctor Command

### From Repository Source

After cloning `tt-a1i/archify`, run directly from the repository root:

```bash
node bin/archify.mjs doctor

```

This pattern appears in the [README at line 208](https://github.com/tt-a1i/archify/blob/main/README.md#L208) and the [authoring cookbook at line 12](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md#L12).

### With npx (Global Installation)

```bash
npx archify doctor

```

### In CI Pipelines

Fail builds automatically when the environment is unhealthy:

```bash
if ! node bin/archify.mjs doctor; then
  echo "❌ Archify environment not ready – aborting"
  exit 1
fi

```

## Understanding Doctor Command Output

### Success State

When all checks pass, the command prints:

```

Archify is ready.

```

And exits with code `0`. The [test suite in `cli.test.mjs` at line 88](https://github.com/tt-a1i/archify/blob/main/archify/test/cli.test.mjs#L88) asserts this exact output:

```javascript
assert.match(doctor, /Archify is ready\./);

```

### Failure States

If any check fails, the command:

- Prints a detailed diagnostic message identifying the specific problem
- Exits with a non‑zero status code
- Suggests remediation (reinstall package, update Node, fix permissions)

## When to Run the Archify Doctor Command

| Scenario | Recommendation |
|----------|---------------|
| First-time setup | Run before any other Archify command |
| After updates | Verify environment still valid post-upgrade |
| CI/CD pipelines | Gate all Archify operations on `doctor` success |
| Troubleshooting | Run to isolate environment vs. usage issues |

## Key Source Files for the Doctor Command

| File | Purpose |
|------|---------|
| `archify/bin/archify.mjs` | Implements `commandDoctor()` — [line 1997](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs#L1997) |
| `archify/test/cli.test.mjs` | Validates success message — [line 88](https://github.com/tt-a1i/archify/blob/main/archify/test/cli.test.mjs#L88) |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) | Primary usage documentation — [line 208](https://github.com/tt-a1i/archify/blob/main/README.md#L208) |
| [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) | Quick-start prerequisite — [line 12](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md#L12) |

## Summary

- The **Archify CLI `doctor` command** is a pre-flight health check for your installation
- It validates **Node version, package integrity, output paths, and validator functionality**
- Run it with `node bin/archify.mjs doctor` from source or `npx archify doctor` globally
- Success produces **"Archify is ready."** with exit code `0`; failures provide actionable diagnostics
- Integrate it into **CI pipelines** to catch environment issues before they break builds

## Frequently Asked Questions

### What Node.js version does Archify doctor require?

Archify requires **Node 18 or newer**. The doctor command checks this first and fails fast with a clear error if your runtime is unsupported, allowing you to upgrade before attempting any rendering or validation operations.

### Can I skip the doctor command and run Archify directly?

You *can*, but the [authoring cookbook](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md#L12) explicitly recommends running `doctor` first. Skipping it risks obscure failures from missing validators, permission issues, or incompatible Node versions that the health check would catch immediately.

### How does the validator integrity check work?

Each validator module is loaded with a special `?doctor=` query parameter that triggers a lightweight self-test. This verifies that validators execute without throwing errors and that their internal dependencies resolve correctly—a unique verification step implemented in `archify/bin/archify.mjs`.

### What exit code does archify doctor return on failure?

The command returns a **non-zero exit status** when any check fails. This makes it safe for shell conditionals and CI pipelines where `if ! archify doctor; then ...` reliably detects problems before proceeding to expensive operations like rendering or batch validation.