solo-check

@withfrontmatter/solo-check is a free, open-source CLI validator. It applies the exact same rules as Solo — without generating anything, without requiring a purchase.

Install and run

npx @withfrontmatter/solo-check

No installation needed with npx. Or install globally:

npm install -g @withfrontmatter/solo-check
frontmatter-check --root .

Options

Option	Description
--root <path>	Astro project root (default: cwd)
--strict	Treat warnings as blocking errors
--json	Machine-readable JSON output
--quiet	Keep only the final summary
--help-ai	Show the AI workflow guide and exit 0
-h, --help	Show help

Example output

Valid project:

✓ src/pages/index.astro — OK
✓ src/layouts/Base.astro — OK
✓ src/pages/contact.astro — OK

──────────────────────────────────────────
0 errors · 0 warnings
──────────────────────────────────────────

Invalid project:

E201 src/pages/index.astro:13 Non-literal props used in component Hero.
  Fix: Use only string, number, boolean, or null props in Solo v1.

E230 src/components/Hero.astro:6 Component-scoped CSS is not supported.
  Fix: Move CSS to a global stylesheet or mark it explicitly global.

──────────────────────────────────────────
2 errors · 0 warnings

Tip: use the AI workflow to fix these errors automatically.
     npx @withfrontmatter/solo-check --help-ai
──────────────────────────────────────────

JSON output

npx @withfrontmatter/solo-check --json

{
  "ok": false,
  "diagnostics": [
    {
      "code": "E201",
      "severity": "error",
      "file": "src/pages/index.astro",
      "line": 13,
      "message": "Non-literal props used in component Hero.",
      "fix": "Use only string, number, boolean, or null props in Solo v1."
    }
  ],
  "exitCode": 1
}

AI workflow

solo-check includes an AI workflow for fixing incompatible Astro code, auditing a project before fixing, or converting generated markup into Solo-compatible Astro.

Open the guide directly:

npx @withfrontmatter/solo-check --help-ai

Included files:

fm-skill.md
README_AI.md
prompts/fix-project.md
prompts/figma-to-astro.md
prompts/audit.md

Exit codes

Code	Meaning
0	Project is compatible with Solo
1	Validation errors found
2	Bad CLI usage
3	Unexpected exception

Contract guarantee

If solo-check exits 0, frontmatter solo:validate will pass with the same result. The contracts are identical — same rules, same diagnostic codes, no divergence.

If you find a case where solo-check and Solo disagree on the same project, that's a bug. Please open an issue on GitHub.

Use in CI

# .github/workflows/check.yml
- name: Check Solo compatibility
  run: npx @withfrontmatter/solo-check --root . --strict --json

Use --json for structured output in CI pipelines. The exit code is reliable for pass/fail gates.

Source

github.com/withfrontmatter/solo-check ↗

← Previous Error codes