Configuration

Capyseo uses a configuration file to customize rules, AI settings, and CI behavior.

Config File Locations

Capyseo searches for config files in this order:

--config <path> flag (explicit path)
capyseo.config.ts
capyseo.config.js
capyseo.config.mjs
.capyseorc.json

Create a Config File

# JavaScript config
capyseo init

# TypeScript config
capyseo init --typescript

Full Configuration Example

/** @type {import('@capyseo/core').CapyseoConfig} */
export default {
  // Rule configuration
  rules: {
    // Severity: 'error' | 'warning' | 'info'
    'meta-title': { severity: 'error' },
    'meta-description': { severity: 'error' },
    'image-alt': { severity: 'error' },
    'heading-hierarchy': { severity: 'warning' },
    'open-graph': { severity: 'warning' },
    'twitter-card': { severity: 'warning' },
    'json-ld': { severity: 'info' },
    'canonical-url': { severity: 'error' },
    'lang-attribute': { severity: 'error' },
    'favicon': { severity: 'warning' },

    // Disable a rule
    'broken-links': { enabled: false },

    // Info-level for less critical rules
    'word-count': { severity: 'info' },
    'readability': { severity: 'info' },
    'security-headers': { severity: 'info' },
  },

  // AI configuration
  ai: {
    enabled: true,
    provider: 'gemini', // 'gemini' | 'openai' | 'anthropic' | 'ollama'
    model: 'gemini-2.5-flash',
    cacheDir: '.capyseo-cache',
    cacheTTL: 86400000, // 24 hours in ms
  },

  // Crawling settings
  crawl: {
    maxPages: 100,
    exclude: ['/admin/*', '/api/*', '/*.pdf'],
    include: ['/*'], // Optional: only analyze matching paths
    respectRobotsTxt: true,
  },

  // CI settings
  ci: {
    minScore: 80,
    failOn: ['error'], // Fail CI if any errors exist
  },
};

Rules Configuration

Each rule can be configured with:

Option	Type	Description
`severity`	`'error' \| 'warning' \| 'info'`	Issue severity level
`enabled`	`boolean`	Enable/disable the rule

Severity Levels

error - Critical SEO issues that should be fixed
warning - Important but not critical
info - Suggestions and minor improvements

Disable a Rule

rules: {
  'broken-links': { enabled: false },
  'word-count': { enabled: false },
}

Change Severity

rules: {
  // Upgrade to error (fail CI)
  'open-graph': { severity: 'error' },

  // Downgrade to info (suggestions only)
  'readability': { severity: 'info' },
}

AI Configuration

ai: {
  enabled: true,
  provider: 'gemini',
  model: 'gemini-2.5-flash',
  cacheDir: '.capyseo-cache',
  cacheTTL: 86400000,
}

Option	Type	Default	Description
`enabled`	`boolean`	`false`	Enable AI suggestions
`provider`	`string`	auto-detected	AI provider to use
`model`	`string`	provider default	Model name
`cacheDir`	`string`	`.capyseo-cache`	Cache directory
`cacheTTL`	`number`	`86400000`	Cache lifetime (ms)

Provider Auto-Detection

If provider is not set, Capyseo checks environment variables:

CAPYSEO_AI_PROVIDER - Explicit provider
GEMINI_API_KEY / GOOGLE_API_KEY → Gemini
OPENAI_API_KEY → OpenAI
ANTHROPIC_API_KEY → Anthropic
Ollama (no key required)

Crawl Configuration

crawl: {
  maxPages: 100,
  exclude: ['/admin/*', '/api/*'],
  include: ['/blog/*', '/docs/*'],
  respectRobotsTxt: true,
}

Option	Type	Default	Description
`maxPages`	`number`	`100`	Maximum pages to analyze
`exclude`	`string[]`	`[]`	Glob patterns to exclude
`include`	`string[]`	`['/*']`	Glob patterns to include
`respectRobotsTxt`	`boolean`	`true`	Honor robots.txt

Glob Patterns

* - Match any characters except /
** - Match any characters including /
? - Match single character

exclude: [
  '/admin/*',      // /admin/anything
  '/api/**',       // /api/v1/users/123
  '/*.pdf',        // /document.pdf
  '**/draft/*',    // /blog/draft/post
]

CI Configuration

ci: {
  minScore: 80,
  failOn: ['error'],
}

Option	Type	Default	Description
`minScore`	`number`	`0`	Minimum acceptable score
`failOn`	`string[]`	`[]`	Severity levels that fail CI

CI Mode Behavior

When using --ci flag:

Score Check: If average score < minScore → exit code 10
Error Check: If failOn: ['error'] and errors exist → exit code 1

# Fail if score < 80 OR any errors exist
capyseo analyze ./dist --ci --min-score 80

TypeScript Config

For TypeScript projects:

// capyseo.config.ts
import type { CapyseoConfig } from '@capyseo/core';

const config: CapyseoConfig = {
  rules: {
    'meta-title': { severity: 'error' },
    // ...
  },
};

export default config;

Environment Variables

Variable	Description
`GEMINI_API_KEY`	Gemini AI API key
`GOOGLE_API_KEY`	Alternative for Gemini
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`CAPYSEO_AI_PROVIDER`	Force specific provider

Per-Project vs Global Config

Project config - capyseo.config.js in project root
CLI override - --config ./path/to/config.js

There is no global config; each project should have its own.

Example Configs

Minimal (Errors Only)

export default {
  rules: {
    'meta-title': { severity: 'error' },
    'meta-description': { severity: 'error' },
    'image-alt': { severity: 'error' },
  },
  ci: { minScore: 70 },
};

Documentation Site

export default {
  rules: {
    'meta-title': { severity: 'error' },
    'meta-description': { severity: 'error' },
    'heading-hierarchy': { severity: 'warning' },
    'word-count': { severity: 'info' }, // Docs vary in length
    'readability': { severity: 'info' }, // Technical content
    'broken-links': { enabled: false }, // Check separately
  },
  ci: { minScore: 80 },
};

E-commerce Site

export default {
  rules: {
    'meta-title': { severity: 'error' },
    'meta-description': { severity: 'error' },
    'image-alt': { severity: 'error' },
    'json-ld': { severity: 'error' }, // Product schema required
    'open-graph': { severity: 'error' }, // Social sharing
    'canonical-url': { severity: 'error' }, // Avoid duplicates
  },
  ai: { enabled: true },
  ci: { minScore: 90, failOn: ['error'] },
};