CLI reference

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

# Emit SARIF for code-scanning tools
astro-doctor --format sarif > astro-doctor.sarif

# Apply safe automatic fixes
astro-doctor --fix

# Preview safe fixes without writing source files
astro-doctor --fix-dry-run

# Explain configuration for a file
astro-doctor explain-config src/pages/index.astro

# Cache repeated scans by file content
astro-doctor --cache

# Save and apply a persistent baseline
astro-doctor baseline create
astro-doctor --baseline .astro-doctor-baseline.json

# Report only diagnostics introduced since main
astro-doctor --scope changed --base main

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

install

Writes the portable skill to skills/astro-doctor.md and offers GitHub Actions setup. Use --agent-hooks for Claude Code and Cursor copies,--dry-run to preview changes, or --yes to accept the setup prompts.

astro-doctor install

baseline create|update|prune

Saves the current findings to .astro-doctor-baseline.json. Subsequent scans with--baseline report only findings that are not already recorded, making gradual adoption practical in existing projects. Reports include new and existing finding counts; resolved counts are shown only for full, unfiltered scans. Resolved means no longer reported under the current configuration, including findings in deleted files.

astro-doctor baseline create
astro-doctor baseline update --output ./config/astro-baseline.json
astro-doctor baseline prune
astro-doctor baseline prune --output ./config/astro-baseline.json

baseline prune removes only recorded occurrences no longer reported, retaining the original timestamp and never accepting new findings. It requires a full scan and rejects file scopes, category filters, explicit project selections, fix flags, and--no-lint. Astro parse failures block baseline comparisons and leave the baseline unchanged. Run pruning with the same preset and configuration used to create the baseline; disabling a rule also removes its findings.

explain-config <file>

Shows the scan preset, effective template rule severities, matching ignore patterns, and zero-based override indexes in application order. Astro files also show exclusion by full-scan discovery, including hidden files without explicit ignore patterns. Workspace files use the same root and project configuration layering as scans. Project audit rules appear separately because template file overrides do not affect them. Inline suppression comments are evaluated during linting and are not part of this configuration report.

astro-doctor explain-config src/pages/index.astro
astro-doctor explain-config src/pages/index.astro --preset strict --json

--fix-dry-run

Simulates the same safe fixes as --fix and prints unified diffs, the net count of findings removed, and remaining findings. Source files and the ESLint cache stay unchanged. Diagnostic counts, scores, and failure gates describe the simulated result. JSON reports include an optional fixPreview object; baseline reports includebaselineProgress, with resolvedCount omitted for partial scans. Combining previews with a baseline shows projected progress after fixes. Use console or JSON output without category filters, --score,--fix, or --no-lint.

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

JSON report schema

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

{
  "$schema": "https://doctor.santi020k.com/schema/report.json",
  "schemaVersion": 1,
  "version": "1.x.x",
  "scoreModel": 2,
  "timestamp": "2024-01-01T00:00:00.000Z",
  "directory": "/my-project",
  "scope": "full",
  "fileCount": 14,
  "errorCount": 1,
  "warningCount": 0,
  "score": 89,
  "scoreLabel": "B",
  "scoreBreakdown": {
    "performance": 100,
    "accessibility": 89,
    "security": 100,
    "best-practices": 100
  },
  "diagnostics": [
    {
      "ruleId": "astro-doctor/no-missing-alt",
      "severity": "error",
      "message": "Image elements must have an alt attribute. Provide a descriptive text for meaningful images, or alt=\"\" for decorative ones.",
      "filePath": "/my-project/src/pages/blog.astro",
      "line": 12,
      "column": 5,
      "category": "accessibility"
    }
  ]
}

Exit codes

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