CLI Reference

Name: astro-doctor
Author: santi020k

astro-doctor [command] [options]

Commands

(no command) — scan

Scans the target directory for Astro issues and prints a health report.

# Scan current directory
    astro-doctor

    # Scan a specific directory
    astro-doctor --dir ./src

    # Scan and write a JSON report
    astro-doctor --json report.json

    # Scan without showing the health score
    astro-doctor --no-score

`install`

Copies the agent skill files (.agents/skills/) into your project root. Run once per project.

astro-doctor install

`experimental-lsp`

Starts the experimental language server in stdio mode (for editor integration without ESLint). This feature is a work in progress.

astro-doctor experimental-lsp --stdio

Options

Flag	Default	Description
`-d, --dir <path>`	`process.cwd()`	Directory to scan
`--json [path]`	off	Output JSON to stdout (no path) or to a file
`--no-score`	show score	Omit the health score from output
`--fail-on <level>`	`error`	Exit 1 on: `error` \| `warning` \| `off`
`--changed-files-from <path>`	off	Scan only files listed in a file (one path per line) — used by the GitHub Action for PR diff mode
`-h, --help`	—	Show help message

JSON report schema

When using --json, the output conforms to this schema:

{
  "$schema": "https://doctor.santi020k.com/schema/config.json",
  "version": "0.1.0",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "directory": "/my-project",
  "fileCount": 14,
  "errorCount": 1,
  "warningCount": 2,
  "score": 85,
  "scoreLabel": "B",
  "diagnostics": [
    {
      "ruleId": "astro-doctor/no-missing-alt",
      "severity": "error",
      "message": "img element is missing a non-empty alt attribute",
      "filePath": "/my-project/src/pages/blog.astro",
      "line": 12,
      "column": 5,
      "category": "accessibility"
    }
  ]
}

Exit codes

Code	Meaning
`0`	Scan completed, no issues at or above the fail-on threshold
`1`	Issues found at or above the fail-on threshold

Examples

# CI: fail on any warning
    astro-doctor --fail-on warning

    # CI: never fail, just report
    astro-doctor --fail-on off

    # Output JSON for downstream tools
    astro-doctor --json | jq '.score'

    # Write JSON to a file and show console output
    astro-doctor --json ./astro-report.json