WebAbility CLI reference

@webability/cli

WCAG accessibility scanner for your terminal. The package installs two commands that behave the same: webability and abilyo.

Install

npm install -g @webability/cli

Quick start

webability scan https://example.com
webability scan localhost:3000
webability scan example.com --format json
webability scan example.com --format html > report.html
webability scan example.com --format sarif > results.sarif
webability scan example.com --exit    # CI mode: exit 1 if issues found
webability scan example.com --viewport mobile

Commands

webability review            # review files changed vs main, added lines only
webability review src/       # review a whole directory
webability flow https://example.com/cart  # follow a journey, one report
webability mcp               # register the MCP server with your editors

Run webability --help or webability <command> --help for the full option list of your installed version.

Configuration

Run webability init to create .webability.yml in your project:

# .webability.yml
project: my-app
urls:
  - http://localhost:3000
standard: WCAG2.1AA
threshold:
  critical: 0
  serious: 5

CI/CD

Use --exit to fail the job when issues are found, and --format sarif to upload results to GitHub code scanning:

# URL scan with SARIF upload
- run: npx @webability/cli scan ${{ env.URL }} --exit --format sarif > results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Pull request review with GitHub Actions

Every pull request gets an accessibility review of its added lines. The review uses the static engine plus one AI turn, posts a PR comment, and fails the check on errors.

1. Create an API key in the dashboard (Developer Tools, API keys). It needs the plan:read permission. Save it as the repo secret WEBABILITY_API_KEY.
2. Save a workflow like the one below as .github/workflows/a11y-review.yml. The full version also posts the report as a PR comment.

name: a11y-review
on:
  pull_request:
    branches: ["**"]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - id: check
        env:
          WEBABILITY_API_KEY: ${{ secrets.WEBABILITY_API_KEY }}
          BASE_REF: ${{ github.base_ref }}
        run: |
          set +e
          FLAG=""; [ -n "$WEBABILITY_API_KEY" ] && FLAG="--agent"
          npx -y "@webability/cli@^1.5.1" review --base "origin/$BASE_REF" $FLAG > "$RUNNER_TEMP/a11y-report.txt"
          echo "exit=$?" >> "$GITHUB_OUTPUT"
      - if: steps.check.outputs.exit != '0'
        run: exit 1

Without a key the workflow still runs the static checks. Findings are limited to added lines. A file whose diff has no added lines (a deletion-only or renamed file) is scanned in full, so an existing issue in such a file can still fail the check. On pull requests from forks the token is read-only, so the report goes to the job summary instead of a PR comment.

@webability/mcp

The MCP package adds these commands. For the hosted server and the tool list, see the MCP setup guide and the API reference.

npm install -g @webability/mcp

webability-mcp (stdio)

Add this to your editor’s MCP config, or run npx -y @webability/mcp:

{
  "mcpServers": {
    "webability": {
      "command": "webability-mcp"
    }
  }
}

The local server runs the browser on your machine, so it can scan http://localhost:3000 directly. The first scan downloads Chromium once. Set WEBABILITY_NO_AUTO_INSTALL=1 to turn the download off. Set WEBABILITY_API_URL to use a self-hosted backend (default https://api.webability.io).

webability-tunnel

The hosted server cannot reach localhost. Use a tunnel only when the scan must run on the hosted server, for example in CI or from a remote agent. Most people should run webability-mcp locally instead.

WEBABILITY_API_KEY=<your-token> npx -y -p @webability/mcp webability-tunnel --port 3000

The command prints a https://tunnel.webability.io/t/<id>/ URL and a secret. Pass the URL as url and the secret as tunnel_secret in scan_page. Options: --port (required), --token (default: the WEBABILITY_API_KEY variable), --relay.

• The URL alone is not enough. Every request must carry the secret.
• Only GET and HEAD requests reach your machine, on the one port you named. Authorization and Cookie headers are removed.
• The tunnel closes after 30 minutes, after 5 minutes idle, or when you press Ctrl-C.

webability-mcp-http

Runs the MCP server over Streamable HTTP for hosting. Set PORT to change the listen port (default 8080).

Docker

docker run -i --rm webabilityio/mcp:latest

Links

• API reference
• MCP setup guide
• @webability/cli on npm
• @webability/mcp on npm
• Support: [email protected]
• All documentation