Installation & Setup

Get from zero to your first scan in under 2 minutes. The installer is license-gated — paste your key directly into the curl command.

Prerequisites

• macOS or Linux — Windows support via WSL2
• A WCAG Audit license key (Pro or above) — get one at wcagaudit.io/pricing

Step 1: Install

Replace <your-license-key> with your actual key. The installer validates the key, downloads the CLI binary, and adds it to your PATH.

curl -fsSL https://wcagaudit.io/install | bash -s -- <your-license-key>

Your license key is saved automatically during install — you won't need to run init separately.

Step 2: Verify your setup

wcag-audit doctor

✓ License: WCAG-XXXX-XXXX-XXXX-XXXX (active, Pro)
✓ AI vision: enabled (included on paid plans)
✓ Framework: Next.js App Router detected
✓ Dev server: npm run dev → port 3000
✓ All checks passed

This checks your license is valid, confirms AI vision is available on your plan, verifies framework detection, and confirms your dev server config.

Step 3 (Next.js): Install the plugin for exact source mapping

The Next.js plugin maps every finding to an exact file:line, enabling 10 deterministic codemods to apply automatically at scan time. Skip this step for non-Next.js projects.

wcag-audit plugin-init

This wraps your next.config.{js,ts,mjs} with withWcagAudit() and adds WCAG_AUDIT=1 to .env.local. Production builds are no-ops when WCAG_AUDIT is not set.

Turbopack (Next 15.4+)

If your project uses npm run dev --turbo (the default in some Next 15 setups), the plugin works there too. withWcagAudit registers loader rules under both webpack and turbopack config keys, so the same WCAG_AUDIT=1 env var activates either bundler.

WCAG_AUDIT=1 npm run dev --turbo

Turbopack reads next.config.{js,ts,mjs} once at startup; the env-gate that decides whether to actually transform JSX is moved into the loader runtime so it's safe to register unconditionally. Production builds (no WCAG_AUDIT env var) are no-op regardless of bundler.

Step 4: Run your first scan

cd ~/my-project
wcag-audit scan

The CLI detects your framework, starts your dev server, discovers all routes, runs codemods on any auto-fixable findings, and audits each route. Results are written to WCAG_FIXES.prompt.md and wcag-report.xlsx.

Alternative: scan a deployed site

Don't have local source? Point the CLI at a live URL instead:

wcag-audit scan --url https://example.com

Project-level config

Create a .wcagauditrc in your project root to customize behavior per-project. This file can be committed to source control.

{
  "routes": "auto",
  "excludePaths": ["/api/*", "/admin/*"],
  "failOn": "critical",
  "outputs": ["excel", "markdown", "ai-fix", "cursor-rules"],
  "devServer": {
    "command": null,
    "port": null,
    "healthCheck": "/"
  }
}

Dynamic routes

Routes like /blog/[slug] are skipped by default. To include them, add sample values:

{
  "dynamicRouteSamples": {
    "/blog/[slug]": ["hello-world", "another-post"],
    "/users/[id]": ["1", "42"]
  }
}