# How to Use the Astryx Doctor Command to Diagnose Setup Issues

> Diagnose Astryx setup issues with the doctor command. Run health checks on your Node environment, package installation, and config files.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/AGENTS.md), [`CLAUDE.md`](https://github.com/facebook/astryx/blob/main/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:

```bash
astryx doctor

```

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

```bash
astryx doctor --json > doctor-report.json

```

Use the exit code in automated pipelines to gate deployments:

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

```json
{
  "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`](https://github.com/facebook/astryx/blob/main/AGENTS.md) or [`CLAUDE.md`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/AGENTS.md) or [`CLAUDE.md`](https://github.com/facebook/astryx/blob/main/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`.