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

# 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`

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

astro-doctor install

`baseline create|update`

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.

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

`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
`--scope <scope>`	`full`	Choose `full`, changed `files`, or introduced diagnostics with `changed`
`--base <ref>`	auto-detected	Base revision for `files` or `changed` scope
`--json [path]`	off	Output JSON to stdout (no path) or to a file
`--fix`	off	Apply safe automatic fixes provided by rules
`--preset <name>`	`recommended`	`recommended` \| `strict` \| `ci` \| `all`
`--cache`	off	Cache ESLint results by file content at `.astro-doctor/cache`; add it to `.gitignore`
`--baseline <path>`	off	Suppress findings recorded in a persistent baseline
`--format <format>`	`console`	Choose `console`, `github`, or `sarif`
`--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/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": 2,
  "score": 85,
  "scoreLabel": "B",
  "scoreBreakdown": {
    "performance": 90,
    "accessibility": 75,
    "security": 100,
    "best-practices": 90
  },
  "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