How to Use the Astryx Doctor Command to Diagnose Setup Issues

The astryx doctor command runs read-only health checks on your Node environment, core package installation, and configuration files to diagnose setup issues before they cause runtime failures.

The astryx doctor command provides a comprehensive diagnostics tool for the Astryx design system. According to the Facebook Astryx source code, this utility validates your project setup without writing to the filesystem, making it safe for both local development and continuous integration pipelines.

How the Doctor Command Works

The diagnostic engine is implemented across several modules in the packages/cli/src directory. The architecture follows a pure, side-effect-free design that only reads the filesystem and environment, never modifying packages or configuration files.

CLI Registration and Dispatch

In packages/cli/src/commands/doctor.mjs, the registerDoctor function adds the command to the main CLI. When invoked, the command determines whether to emit a human-readable checklist (default) or JSON output when the --json flag is provided.

Context Collection

The runChecks function in packages/cli/src/api/doctor.mjs builds a DoctorContext object containing the current working directory (cwd), Node.js version from process.versions.node, and the resolved path to @astryxdesign/core via findCoreDir. It also locates your astryx.config.mjs file using findConfigPath and extracts any configured theme.

Synchronous Health Checks

An ordered array named SYNC_CHECKS defines pure functions that each return a DoctorCheck record. Type definitions for these structures reside in packages/cli/src/types/doctor.d.ts. The checks include:

• checkNodeVersion: Verifies the Node.js version meets the minimum requirement.
• checkCoreInstalled: Ensures @astryxdesign/core can be resolved from the project root.
• checkVersionAlignment: Warns when the core and CLI versions drift apart.
• checkThemes: Scans for installed @astryxdesign/theme-* packages and validates theme wiring.
• checkAgentDocs: Confirms that AI-agent documentation files (AGENTS.md, CLAUDE.md, etc.) contain the required XDS markers.
• checkPeerDeps: Validates that peer dependencies declared by @astryxdesign/core are present in your project.
• checkPackageManager: Reports the detected package manager via the utilities in packages/cli/src/utils/package-manager.mjs.

Asynchronous Configuration Validation

After synchronous checks complete, runChecks invokes checkConfig (the only asynchronous check) to load astryx.config.mjs and verify that its default export is a valid object. This logic is implemented in packages/cli/src/lib/project.mjs.

Result Aggregation and Output

All DoctorCheck objects are collected into a DoctorReport with a computed summary containing counts for pass, warn, fail, and info. If --json is not supplied, printHuman formats the report as a monochrome checklist using Unicode glyphs (✓, ⚠, ✗, ℹ). The command sets the process exit code to 1 when any check fails, making it suitable as a CI gate.

Running the Doctor Command

Execute the diagnostic from your project root:

astryx doctor

For machine-readable output suitable for CI scripts or AI agents:

astryx doctor --json > doctor-report.json

Use the exit code in automated pipelines to gate deployments:

if ! astryx doctor; then
  echo "Setup validation failed"
  exit 1
fi

Sample JSON Output Structure

When using --json, the command outputs a structured report containing check IDs, human-readable labels, status values, and optional fix instructions:

{
  "type": "doctor",
  "data": {
    "checks": [
      {
        "id": "node-version",
        "label": "Node.js version",
        "status": "pass",
        "message": "Node v18.17.0 meets the minimum (>=18.0.0)."
      },
      {
        "id": "core-installed",
        "label": "@astryxdesign/core installed",
        "status": "fail",
        "message": "@astryxdesign/core could not be resolved from this project.",
        "fix": "Install the design system: `npm install @astryxdesign/core` (or yarn/pnpm/bun)."
      }
    ],
    "summary": { "pass": 5, "warn": 1, "fail": 1, "info": 2 }
  }
}

Summary

• The astryx doctor command performs read-only diagnostics on your project environment and configuration, implemented in packages/cli/src/api/doctor.mjs.
• The engine runs synchronous checks for Node versions, core installation (checkCoreInstalled), themes (checkThemes), and peer dependencies (checkPeerDeps) before validating the config file asynchronously.
• The command exits with code 1 if any checks fail, supporting both --json machine-readable output and human-friendly Unicode formatting.
• Key utilities include findCoreDir and findConfigPath in packages/cli/src/utils/paths.mjs, and project configuration loading in packages/cli/src/lib/project.mjs.

Frequently Asked Questions

What specific validations does the doctor command perform?

The command validates Node.js version compatibility, @astryxdesign/core installation and version alignment, theme package presence, AI-agent documentation markers in AGENTS.md or CLAUDE.md, peer dependency satisfaction, and configuration file syntax. Each check is implemented as a pure function in the SYNC_CHECKS array within packages/cli/src/api/doctor.mjs.

Can I integrate astryx doctor into CI/CD pipelines?

Yes. The command is designed to be side-effect-free and returns exit code 1 when any check fails, making it ideal for CI gates. Use astryx doctor --json to produce machine-readable reports that automation can parse, and pipe the output to files for artifact collection.

What are AI-agent documentation markers?

Astryx requires specific XDS markers in files like AGENTS.md or CLAUDE.md to ensure AI coding assistants understand the design system context. The checkAgentDocs validation inspects these files for required markers, helping maintain consistent AI-assisted development workflows.

How does the doctor command locate the Astryx configuration and core package?

The findConfigPath utility searches for astryx.config.mjs while findCoreDir resolves the @astryxdesign/core package path using Node module resolution. These utilities are implemented in packages/cli/src/utils/paths.mjs and invoked during context creation in packages/cli/src/api/doctor.mjs.

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