Documentation

Install, configure, and run a11yscan in minutes.

Installation

macOS / Linux

pnpm add -g a11yscan
npx playwright install chromium

Windows requires WSL2 with Ubuntu. See the README for details.

Quick start

Just give it a URL. Protocol and /sitemap.xml are optional:

# These are all equivalent:
a11yscan example.com
a11yscan https://example.com
a11yscan --sitemap https://example.com/sitemap.xml

Two ways to scan

a11yscan supports two modes: direct mode for quick, scriptable scans and interactive mode for guided setup when you're not sure what flags to use.

Direct mode

Pass a URL and flags directly. Best for repeat scans, scripts, and CI/CD.

# Scan an entire site
a11yscan example.com

# Scan just the /about section
a11yscan example.com/about

# Exclude paths, limit pages
a11yscan example.com --filter "/research" \
  --exclude "/research/archive" --limit 50

Interactive wizard

Run a11yscan with no arguments. The wizard walks you through every option step by step.

Terminal

$ a11yscan

? Site URL: example.com
? Sitemap URL (enter for auto): 
? Include path: /about
? Exclude paths: /about/archive
? Output formats: csv,json,html
? Concurrency (1-5): 5
? Reports to keep: 3

Starting scan...

Both modes produce identical results. Use direct mode when you know what you want; use the wizard when you're exploring a new site or want to double-check your configuration before scanning.

CLI reference

CLI flags and options
Flag	Default	Description
[url]	—	Site URL — includes path to auto-filter a section (e.g., example.com/about)
--sitemap <url>	—	Explicit URL to sitemap.xml
--filter <path>	all	Path prefix to include (e.g., /research)
--filter-glob <pattern>	—	Glob pattern for URL pathname matching
--exclude <paths>	—	Comma-separated path prefixes to exclude
--depth <n>	—	Max URL path depth to include
--limit <n>	—	Max number of pages to scan
--output <formats>	csv,json,html	Comma-separated: csv, json, html, md
--filename <name>	auto	Base filename for reports
--concurrency <n>	5	Parallel pages to scan (1-5)
--keep <n>	3	Report runs to keep per site/section (0 = no pruning)
--ci	false	CI mode: JSON to stdout, exit codes

Examples

Scan a section by URL path

a11yscan example.com/about
# Reports saved to reports/example.com/about/{timestamp}/

Scan a nested section

a11yscan example.com/research/articles
# Reports saved to reports/example.com/research/articles/{timestamp}/

Scan a section with explicit filter

a11yscan example.com --filter "/about"

Exclude sections

a11yscan example.com --exclude "/blog,/archive"

Glob pattern matching

a11yscan example.com --filter-glob "/*/services/**"

Limit scan scope

a11yscan example.com --filter "/news" --limit 20

Custom report name

a11yscan example.com --filename "q1-audit"

Markdown for GitHub issues

a11yscan example.com --output csv,json,html,md

Interactive wizard

a11yscan
# Walks through site, sitemap, include/exclude, output, concurrency

Prune old reports

a11yscan prune example.com --keep 3
# Or prune all sites: a11yscan prune --all

CI/CD mode

a11yscan example.com --ci --output json

Exit codes

Exit codes
Code	Meaning
0	Scan complete, no violations found
1	Scan complete, violations found
2	Configuration or fetch error
3	Scan interrupted (partial results written)

Chromium dependencies

Ubuntu / Debian

Install system libraries required by headless Chromium:

sudo apt-get update && sudo apt-get install -y \
  libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
  libxcomposite1 libxdamage1 libxrandr2 libgbm1 \
  libpango-1.0-0 libcairo2 libasound2

npx playwright install chromium

macOS

No extra system packages needed — just install the browser binary:

npx playwright install chromium

CI/CD (GitHub Actions)

.github/workflows/a11y.yml

- name: Accessibility audit
  run: |
    npx playwright install chromium
    a11yscan ${{ env.SITE_URL }} --ci --output json

System requirements

System requirements by platform
Platform	Minimum	Notes
macOS	macOS 12+ (Monterey), Node.js 18+	No extra system packages needed
Ubuntu / Debian	Ubuntu 22.04+, Node.js 18+	Requires Chromium system libraries (see above)
Windows	Windows 10/11 + WSL2, Ubuntu 22.04+, Node.js 18+	Native Windows not supported — requires WSL2

All platforms require pnpm (or npm/yarn) and a Chromium binary installed via Playwright.

Building from source

Clone the repo and install dependencies:

git clone https://github.com/ICJIA/a11yscan.dev.git
cd a11yscan.dev
pnpm install
npx playwright install chromium

# Build the CLI
pnpm build

# Run tests
pnpm test

# Optional: create a shell alias
alias a11yscan='node ./packages/cli/dist/index.js'