Getting Started

Capyseo is a framework-agnostic SEO toolkit that helps you find and fix SEO issues in your website.

Installation

CLI (Recommended)

# Run directly with bunx
bunx @capyseo/cli analyze ./dist

# Or install globally
bun add -g @capyseo/cli

Library

bun add @capyseo/core

SvelteKit Adapter

bun add @capyseo/adapter-sveltekit

Basic Usage

Analyze a Directory

Analyze all HTML files in a directory:

capyseo analyze ./dist

Analyze a Live Site

Crawl and analyze a live website:

capyseo analyze https://example.com

Enable AI Features

Use Gemini AI to generate meta descriptions and alt text:

GEMINI_API_KEY=your-key capyseo analyze ./dist --ai

Configuration

Create a config file to customize rules:

capyseo init

This creates capyseo.config.js:

export default {
  rules: {
    'meta-title': { severity: 'error' },
    'meta-description': { severity: 'error' },
    'image-alt': { severity: 'error' },
    'open-graph': { severity: 'warning' },
  },
  ai: {
    enabled: true,
    model: 'gemini-2.5-flash',
  },
  ci: {
    minScore: 80,
    failOn: ['error'],
  },
};

CI Integration

Use in your CI pipeline:

capyseo analyze ./dist --ci --min-score 80 --format sarif -o seo-report.sarif

Exit codes:

0 - Analysis passed
1 - Score below minimum or errors found

Output Formats

Format	Description
`console`	Human-readable terminal output
`json`	Detailed JSON report
`sarif`	SARIF format for GitHub Code Scanning
`html`	Standalone HTML report
`csv`	CSV for spreadsheet analysis

What's Checked

Capyseo includes 30+ built-in rules:

Meta Tags: Title, description, viewport, charset
Images: Alt text, lazy loading, dimensions
Headings: H1 presence, hierarchy
Technical: Canonical URLs, robots meta, hreflang
Social: Open Graph, Twitter Cards
Structured Data: JSON-LD validation
Links: Broken links, redirect chains
Content: Word count, readability
Mobile: Viewport, touch targets
Security: HTTPS, security headers