@capyseo/cli

Command-line SEO analyzer with AI-powered suggestions for any website or framework.

Documentation · GitHub · Report Issue

Part of the Capyseo toolkit.

Overview

A powerful command-line SEO analyzer that scans your websites for issues and provides AI-powered suggestions to improve search rankings. Works with any framework or static site.

What Can It Do?

🔍 Analyze any website — Local build folders, live URLs, or crawl entire sites
🤖 AI-powered suggestions — Generate meta descriptions, alt text, and content improvements
📊 Multiple output formats — Console, JSON, HTML reports, CSV, SARIF (for GitHub)
🚀 CI/CD integration — Fail builds on low SEO scores with exit codes
📝 Generate SEO assets — Create sitemaps, robots.txt, and meta tags
👀 Watch mode — Re-analyze automatically when files change

Installation

Global Installation (Recommended)

Install globally to use the capyseo command anywhere:

# Using npm
npm install -g @capyseo/cli

# Using Bun
bun add -g @capyseo/cli

# Using pnpm
pnpm add -g @capyseo/cli

Run Without Installing

Use npx or bunx to run without installing:

# Using npx
npx @capyseo/cli analyze ./dist

# Using bunx (faster)
bunx @capyseo/cli analyze ./dist

Verify Installation

capyseo --version
capyseo --help

Quick Start

Analyze a Built Site

After building your site (e.g., npm run build), analyze the output folder:

capyseo analyze ./dist

Output:

Analyzing 5 pages...

/index.html
   Score: 85/100

   ✗ [meta-description] Missing meta description
     → Add <meta name="description" content="...">

   ! [open-graph] Missing og:image
     → Add <meta property="og:image" content="...">

/about.html
   Score: 92/100

   ✓ No issues found!

==================================================
Average Score: 88.5/100
Total Pages: 5
Total Issues: 3

Analyze a Live URL

capyseo analyze https://example.com

Crawl an Entire Website

# Crawl up to 50 pages following links
capyseo analyze https://example.com --max-pages 50

Get AI-Powered Suggestions

# Using OpenAI (requires API key)
OPENAI_API_KEY=sk-xxx capyseo analyze ./dist --ai

# Using Ollama (free, local)
capyseo analyze ./dist --ai --ai-provider ollama

Commands

`capyseo analyze`

The main command for SEO analysis.

capyseo analyze <target> [options]

Arguments:

Argument	Description	Examples
`target`	Path to folder, HTML file, or URL	`./dist`, `./build/index.html`, `https://example.com`

Options:

Option	Description	Default
`--ai`	Enable AI-powered suggestions	`false`
`--ai-provider <provider>`	AI provider: `openai`, `anthropic`, `gemini`, `ollama`	`openai`
`--spa`	Enable JavaScript rendering for SPAs	`false`
`--format <format>`	Output format: `console`, `json`, `html`, `csv`, `sarif`	`console`
`-o, --output <path>`	Write output to file	stdout
`--max-pages <n>`	Maximum pages to crawl	`100`
`--ci`	CI mode: exit with code 1 on issues	`false`
`--min-score <n>`	Minimum acceptable score (with `--ci`)	`0`
`--no-live`	Disable HTTP checks for broken links	enabled
`--exclude <patterns>`	Glob patterns to exclude	none
`--config <path>`	Path to config file	auto-detected
`-v, --verbose`	Show detailed output	`false`
`-q, --quiet`	Only show errors	`false`

Examples:

# Basic analysis
capyseo analyze ./dist

# With AI suggestions using OpenAI
OPENAI_API_KEY=xxx capyseo analyze ./dist --ai

# With AI using local Ollama
capyseo analyze ./dist --ai --ai-provider ollama

# Generate HTML report
capyseo analyze ./dist --format html -o report.html

# CI mode with minimum score
capyseo analyze ./dist --ci --min-score 80

# Analyze SPA (renders JavaScript)
capyseo analyze https://spa.example.com --spa

# Exclude certain paths
capyseo analyze ./dist --exclude "admin/*" --exclude "api/*"

`capyseo generate`

Generate SEO-related files.

`capyseo generate sitemap`

Generate an XML sitemap from a folder or by crawling a URL.

capyseo generate sitemap <target> --origin <url> [options]

Option	Description	Default
`--origin <url>`	Base URL for sitemap (required)	-
`-o, --output <path>`	Output file path	`sitemap.xml`
`--changefreq <freq>`	Default change frequency	`weekly`
`--priority <n>`	Default priority (0.0-1.0)	`0.5`

Example:

# Generate sitemap from build folder
capyseo generate sitemap ./dist --origin https://example.com -o ./dist/sitemap.xml

# Crawl and generate
capyseo generate sitemap https://example.com --origin https://example.com

Output (sitemap.xml):

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://example.com/about</loc>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>

`capyseo generate robots`

Generate a robots.txt file.

capyseo generate robots [options]

Option	Description	Default
`-o, --output <path>`	Output file path	`robots.txt`
`--sitemap <url>`	Sitemap URL to include	-
`--disallow <paths>`	Paths to disallow (can be repeated)	-

Example:

capyseo generate robots -o ./dist/robots.txt \
  --sitemap https://example.com/sitemap.xml \
  --disallow /admin \
  --disallow /api

Output (robots.txt):

User-agent: *
Allow: /

Disallow: /admin
Disallow: /api

Sitemap: https://example.com/sitemap.xml

`capyseo generate meta`

Generate meta tags using AI (requires API key).

capyseo generate meta <url> [options]

Option	Description	Default
`--ai-provider <provider>`	AI provider	`openai`

Example:

OPENAI_API_KEY=xxx capyseo generate meta https://example.com/about

Output:

<!-- Suggested meta tags for https://example.com/about -->

<title>About Us — Example Company | Who We Are</title>
<meta name="description" content="Learn about Example Company's mission, team, and values. We've been helping customers succeed since 2010.">

<!-- Open Graph -->
<meta property="og:title" content="About Us — Example Company">
<meta property="og:description" content="Learn about Example Company's mission, team, and values.">
<meta property="og:type" content="website">
<meta property="og:url" content="https://example.com/about">

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="About Us — Example Company">
<meta name="twitter:description" content="Learn about Example Company's mission, team, and values.">

`capyseo watch`

Watch for file changes and re-analyze automatically.

capyseo watch <directory> [options]

Option	Description	Default
`--debounce <ms>`	Debounce delay	`500`
All `analyze` options	Same as analyze command	-

Example:

# Watch build folder during development
capyseo watch ./dist

# Watch with AI suggestions
OPENAI_API_KEY=xxx capyseo watch ./dist --ai

`capyseo init`

Create a configuration file interactively.

capyseo init

This creates a capyseo.config.js file in your project root.

Output Formats

Console (Default)

Human-readable output for terminal:

capyseo analyze ./dist

JSON

Machine-readable JSON for scripting:

capyseo analyze ./dist --format json -o report.json

{
  "summary": {
    "averageScore": 85,
    "totalPages": 5,
    "totalIssues": 12
  },
  "reports": [
    {
      "url": "/index.html",
      "score": 85,
      "issues": [
        {
          "rule": "meta-description",
          "severity": "error",
          "message": "Missing meta description"
        }
      ]
    }
  ]
}

HTML Report

Interactive HTML report with charts:

capyseo analyze ./dist --format html -o report.html

Features:

Score overview chart
Filter by severity
Search issues
Expandable details
Print-friendly

CSV

Spreadsheet-compatible format:

capyseo analyze ./dist --format csv -o report.csv

SARIF (GitHub Code Scanning)

SARIF format for GitHub Security tab:

capyseo analyze ./dist --format sarif -o report.sarif

Then upload in GitHub Actions:

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: report.sarif

AI-Powered Analysis

Capyseo can use AI to generate smart suggestions for:

Meta descriptions — Based on page content
Image alt text — Based on surrounding context
Title improvements — More engaging, keyword-rich titles
Content recommendations — Readability and keyword suggestions

Setting Up AI

OpenAI (GPT-4o)

# Set API key
export OPENAI_API_KEY=sk-your-key-here

# Run with AI
capyseo analyze ./dist --ai --ai-provider openai

Anthropic (Claude Sonnet 4.5)

export ANTHROPIC_API_KEY=sk-ant-your-key-here
capyseo analyze ./dist --ai --ai-provider anthropic

Google Gemini (Recommended)

export GEMINI_API_KEY=your-key-here
capyseo analyze ./dist --ai --ai-provider gemini

Ollama (Free, Local)

Install Ollama: https://ollama.ai
Pull a model:
```
ollama pull deepseek-r1:8b
```

Run analysis:

capyseo analyze ./dist --ai --ai-provider ollama

Recommended Ollama models by hardware:

Hardware	Model
RTX 4090 (24GB)	`deepseek-r1:70b`
RTX 4070 (12GB)	`qwen3-coder:14b`
RTX 3070 (8GB)	`deepseek-r1:8b`
M4 Pro (48GB)	`deepseek-r1:70b`
M4 (16GB)	`qwen3-coder:14b`
CPU only	`phi-3:3.8b`

CI/CD Integration

GitHub Actions

# .github/workflows/seo.yml
name: SEO Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  seo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install

      - name: Build site
        run: bun run build

      - name: Run SEO analysis
        run: bunx @capyseo/cli analyze ./dist --ci --min-score 80

      - name: Upload SARIF report
        if: always()
        run: bunx @capyseo/cli analyze ./dist --format sarif -o seo.sarif

      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: seo.sarif

GitLab CI

# .gitlab-ci.yml
seo:
  stage: test
  image: oven/bun:latest
  script:
    - bun install
    - bun run build
    - bunx @capyseo/cli analyze ./dist --ci --min-score 80
  artifacts:
    reports:
      sast: seo.sarif
    paths:
      - seo.sarif

Exit Codes

Code	Meaning
`0`	Success (or no `--ci` flag)
`1`	Score below `--min-score` or errors found

Configuration File

Create capyseo.config.js in your project root:

// capyseo.config.js
export default {
  // Rule configuration
  rules: {
    // Change severity levels
    'meta-title': { severity: 'error' },
    'meta-description': { severity: 'error' },
    'open-graph': { severity: 'warning' },

    // Disable rules
    'twitter-card': { enabled: false },

    // Custom thresholds
    'content-length': { minWords: 300 },
    'meta-title-length': { min: 30, max: 60 },
  },

  // AI configuration
  ai: {
    provider: 'openai',  // 'openai' | 'anthropic' | 'gemini' | 'ollama'
    enabled: false,      // Set to true, or use --ai flag
  },

  // Path patterns to exclude
  exclude: [
    'admin/*',
    'api/*',
    '*.json',
  ],

  // CI/CD settings
  ci: {
    minScore: 80,
    failOn: ['error'],  // 'error' | 'warning' | 'info'
  },

  // Output settings
  output: {
    format: 'console',
    file: null,
  },
};

Examples

Analyze a Next.js Build

# After running `next build`
capyseo analyze ./out

Analyze an Astro Build

# After running `astro build`
capyseo analyze ./dist

Analyze a SvelteKit Build

# After running `vite build`
capyseo analyze ./build

Pre-commit Hook

Using Husky:

# .husky/pre-commit
bunx @capyseo/cli analyze ./dist --ci --min-score 70

Compare Before/After

# Baseline
capyseo analyze ./dist --format json -o before.json

# Make changes, rebuild

# Compare
capyseo analyze ./dist --format json -o after.json
diff before.json after.json

Troubleshooting

"No HTML files found"

Make sure the path points to a folder containing .html files or a URL:

# Wrong: pointing to source folder
capyseo analyze ./src

# Right: pointing to build output
capyseo analyze ./dist

"AI suggestions not appearing"

Check your API key is set:
```
echo $OPENAI_API_KEY
```
Make sure you're using the --ai flag:
```
capyseo analyze ./dist --ai
```

"SPA shows empty/low content"

Your site might render content with JavaScript. Enable SPA mode:

# Install Playwright first
npm install playwright
npx playwright install chromium

# Then analyze
capyseo analyze https://spa.example.com --spa

"Broken link checks are slow"

Disable live HTTP checks if you don't need them:

capyseo analyze ./dist --no-live

Related Packages

Package	Description
@capyseo/core	Core analysis engine (programmatic API)
@capyseo/sveltekit	SvelteKit integration with Vite plugin & hooks

Support

📖 Documentation
✉️ Email
💬 Discussions
🐛 Issues

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT © Capyseo

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github		.github
assets		assets
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
biome.json		biome.json
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

License

Capyseo/capyseo-cli

Folders and files

Latest commit

History

Repository files navigation

@capyseo/cli

Overview

What Can It Do?

Table of Contents

Installation

Global Installation (Recommended)

Run Without Installing

Verify Installation

Quick Start

Analyze a Built Site

Analyze a Live URL

Crawl an Entire Website

Get AI-Powered Suggestions

Commands

capyseo analyze

capyseo generate

capyseo generate sitemap

capyseo generate robots

capyseo generate meta

capyseo watch

capyseo init

Output Formats

Console (Default)

JSON

HTML Report

CSV

SARIF (GitHub Code Scanning)

AI-Powered Analysis

Setting Up AI

OpenAI (GPT-4o)

Anthropic (Claude Sonnet 4.5)

Google Gemini (Recommended)

Ollama (Free, Local)

CI/CD Integration

GitHub Actions

GitLab CI

Exit Codes

Configuration File

Examples

Analyze a Next.js Build

Analyze an Astro Build

Analyze a SvelteKit Build

Pre-commit Hook

Compare Before/After

Troubleshooting

"No HTML files found"

"AI suggestions not appearing"

"SPA shows empty/low content"

"Broken link checks are slow"

Related Packages

Support

Contributing

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

`capyseo analyze`

`capyseo generate`

`capyseo generate sitemap`

`capyseo generate robots`

`capyseo generate meta`

`capyseo watch`

`capyseo init`

Packages