BLOG · ACCESSIBILITY TESTING

Automated Accessibility Scanning
from the Command Line

How to check any website for WCAG and European Accessibility Act issues straight from your terminal — and how to wire it into CI so regressions never ship.

Start Reading Download the CLI → →

Updated August 2026 · Reading time: 6 minutes

why-cli

Browser-based accessibility checkers are fine for a one-off audit, but they do not scale. If you maintain more than a handful of sites — or you want every deploy checked automatically — you need scanning that runs where your code runs: the terminal and your CI pipeline. A CLI scanner fits both. It takes a URL or a local HTML file, applies a fixed ruleset, and exits with a status code your build can act on.

⌨️ Scriptable

Pipe results into reports, fail builds on errors, scan a whole sitemap in a loop. Anything you can type, you can automate.

🔒 Runs Locally

No account, no upload. The page HTML is fetched and analysed on your own machine — safe for client sites under NDA.

🔁 CI-Ready

A --fail-on flag turns accessibility errors into build failures, so a regression is caught before deployment, not by a client.

what-it-checks

The eaa-scanner applies 16 rules drawn from WCAG 2.1/2.2 Level A/AA success criteria — the same criteria the European Accessibility Act references. Each rule maps to a concrete fix:

• IMG_ALT — images without alt attributes (WCAG 1.1.1)

• FORM_LABEL — inputs without associated labels (WCAG 1.3.1, 4.1.2)

• CONTRAST — text/background colour pairs below the 4.5:1 ratio, computed via relative luminance (WCAG 1.4.3)

• HTML_LANG — missing lang attribute on <html> (WCAG 3.1.1)

• PAGE_TITLE — missing or empty title element (WCAG 2.4.2)

• HEADING_ORDER / H1_MISSING — skipped heading levels, pages without an h1 (WCAG 1.3.1)

• BUTTON_TEXT / LINK_TEXT — buttons and links with no discernible text (WCAG 2.4.4, 4.1.2)

• DUP_ID — duplicate id attributes breaking label/aria associations (WCAG 4.1.1)

• TARGET_BLANK — links opening in new tabs without warning (WCAG 3.2.5 advisory)

Each finding is classified as an error or a warning and comes with a one-line fix tip.

install-and-use

Two distributions, same engine and identical output:

Node.js (npm): npm install https://hermes-passiv.pages.dev/downloads/mahope-eaa-scanner-1.0.0.tgz — then npx eaa-scan https://example.com. Zero dependencies; works on Node 18+.

Python: download the wheel from the downloads page and pip install it — then eaa-scan https://example.com. Also zero runtime dependencies.

Both accept multiple URLs and local HTML files in one run. Use --json for machine-readable output and --fail-on error (or warning) to set the CI threshold: exit code 0 means clean, 1 means findings at or above the threshold.

ci-pipeline

The point of a CLI scanner is that nobody has to remember to run it. A minimal GitHub Actions workflow checks every push:

name: accessibility
on: [push]
jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install https://hermes-passiv.pages.dev/downloads/mahope-eaa-scanner-1.0.0.tgz
      - run: npx eaa-scan https://yoursite.example --fail-on error

Start with --fail-on error so only unambiguous failures block the build, then tighten to warnings once the obvious issues are fixed. The same pattern works in GitLab CI, CircleCI, or a plain pre-deploy script.

limits

Automated tools catch roughly 30-50% of WCAG issues — the mechanical ones. Keyboard traps, logical focus order, meaningful alt text, and colour contrast that depends on overlaid images all need human judgement. Treat the scanner as a floor, not a ceiling: an automated pass means no known mechanical defects, not full compliance. Pair it with a keyboard-only walkthrough of your key user flows once per release.

Also note what a static-HTML scanner deliberately does not do: it does not execute JavaScript. Content rendered client-side after load may need a browser-based tool as a complement. For most marketing sites, documentation sites, and CMS-rendered pages, server-rendered HTML is the majority of the surface — and that is exactly what the scanner covers.

Going Deeper

The eaa-scanner CLI is free, runs locally, and sends nothing anywhere. Available as a Python package and an npm package with zero dependencies — install instructions and tarballs on the downloads page.

Try the Free Web Scanner → → Download the CLI → →

Frequently Asked Questions

Is the eaa-scanner really free?

Yes. Both the Python and Node.js versions are free to use, including in commercial and CI contexts. There is no account, no API key, and no usage limit — the scanning happens entirely on your machine.

Does sending my URL to the scanner leak anything?

No data leaves your machine except the ordinary HTTP request fetching the page you asked to scan — the same request your browser would make. Results are computed locally and printed to your terminal.

Can it scan pages behind a login?

Not directly — it fetches public URLs. For authenticated pages, save the rendered HTML to a file and pass the file path instead; the scanner analyses local files identically.

What score should I aim for?

The scanner grades A-F. Errors are WCAG failures that block assistive technology users; warnings are best-practice issues. Aim for zero errors first (grade C or better), then work through warnings toward an A.

How is this different from Lighthouse?

Lighthouse bundles performance, SEO and a small accessibility subset into a browser-based audit. eaa-scanner focuses purely on accessibility markup rules, runs without a browser, includes contrast computation, and is designed to fail CI builds. They complement each other.