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

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:

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:

node bin/archify.mjs doctor

This pattern appears in the README at line 208 and the authoring cookbook at line 12.

With npx (Global Installation)

npx archify doctor

In CI Pipelines

Fail builds automatically when the environment is unhealthy:

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 asserts this exact output:

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
archify/test/cli.test.mjs	Validates success message — line 88
README.md	Primary usage documentation — line 208
docs/authoring-cookbook.md	Quick-start prerequisite — line 12

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

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