@allyproof/cli

Run WCAG 2.2 AA accessibility scans, fetch history, and gate CI/CD pipelines from your terminal.

@allyproof/cli is the official command-line client for AllyProof — a WCAG accessibility scanner that audits live sites with axe-core, HTML_CodeSniffer, and APCA contrast checking. Use it to trigger scans on demand, embed accessibility gates in your CI/CD pipeline, or pull recent scan results from the terminal without leaving your editor.

Install

npm install -g @allyproof/cli
allyproof --version

Or run via npx in CI to avoid a persistent install:

npx @allyproof/cli scan https://example.com --threshold 80

Requires Node.js 20+.

Get an API key

The CLI talks to your AllyProof organization, so you need an account + an API key first. The whole thing takes about a minute:

1. Sign up at allyproof.com/signup — email + password, or Google / GitHub OAuth. The free plan includes scans on the dashboard side and is enough to try the CLI.
2. Verify email if prompted (one click from the inbox).
3. Generate a key: open allyproof.com/settings/api-keys, click Generate new key, give it a name (e.g. local-dev or github-actions), and copy the value once — AllyProof only displays it on creation.

Keys are scoped to the organization that created them and inherit that org's plan limits. They never expire automatically; revoke from the same page when a key leaks or you rotate.

Authenticate the CLI

Once you have a key:

allyproof login              # interactive — paste the key when prompted
allyproof login --key ap_live_…   # non-interactive (good for CI bootstrap)
allyproof whoami             # confirms which org the key belongs to

The key is written to ~/.config/allyproof/config.json on POSIX (mode 0600) or %APPDATA%\allyproof\config.json on Windows. In CI, prefer the env var so the key never lands on disk:

export ALLYPROOF_API_KEY=ap_live_…

Commands

allyproof scan [url]

Run a WCAG scan. Pass either a URL or --site <id> (a tracked site in your org).

| Flag | Purpose | |---|---| | --site <id> | Scan a tracked site by id. Faster than URL form (skips resolution). Recommended for CI. | | --threshold <n> | Exit 1 if the score is below n (0–100). | | --fail-on <list> | Exit 1 if any violation of the listed severities is present. Comma-separated subset of critical,serious,moderate,minor. | | --max-pages <n> | Cap the page budget for this scan (overrides the site default). | | --no-wait | Enqueue and return immediately with the scan_id — pair with allyproof show <scanId> later. | | --output <format> | pretty (default), json, sarif, junit. SARIF feeds GitHub code-scanning; JUnit drops into Jenkins / GitLab test panels. | | --json | Shortcut for --output json. |

Examples:

allyproof scan https://example.com
allyproof scan --site 9b15692d-…              # site-id form (faster, CI-friendly)
allyproof scan --site $SITE --threshold 80 --fail-on critical,serious
allyproof scan --site $SITE --output sarif > a11y.sarif

--no-wait is incompatible with --output sarif and --output junit — those formats need the full violation list. Run without --no-wait (or follow up with allyproof show <scanId> --output sarif).

allyproof history

List recent scans for the authenticated organization.

| Flag | Purpose | |---|---| | --site <id> | Filter to a single site. | | --status <status> | One of pending, running, completed, failed, cancelled. | | --limit <n> | Max rows (1–100, default 20). | | --cursor <iso> | Pagination cursor returned by a previous call. | | --json | Emit raw JSON. |

allyproof history --limit 10
allyproof history --site 9b15692d-… --status completed
allyproof history --cursor 2026-04-29T08:30:00Z   # next page from the previous response

allyproof show <scanId>

Full details for a single scan.

| Flag | Purpose | |---|---| | --include-advisory | Include manual-review (advisory) items in the violations list. | | --include-resolved | Include violations resolved or dismissed in this scan (default shows only open). | | --include-history | Show all rolled-up site issues, not just what was detected in this scan. | | --output <format> | pretty (default), json, sarif, junit. | | --json | Shortcut for --output json. |

allyproof show abc123…
allyproof show abc123… --include-advisory --output sarif > a11y.sarif

allyproof diff <scanA> <scanB>

Compare two scans. scanA is the baseline, scanB is the new state.

| Flag | Purpose | |---|---| | --json | Emit raw JSON instead of pretty output. |

allyproof diff abc123… def456…

allyproof open <scanId>

Open the scan in the AllyProof dashboard in your default browser.

| Flag | Purpose | |---|---| | --print | Print the URL to stdout instead of launching the browser. |

allyproof open abc123…
allyproof open abc123… --print          # in CI / headless: capture URL for a notification

allyproof sites list

List tracked sites in the organization.

| Flag | Purpose | |---|---| | --json | Emit raw JSON. |

allyproof sites add <url>

Register a new site. Returns the site id and a verification token.

| Flag | Purpose | |---|---| | --name <name> | Required. Display name. | | --method <method> | meta_tag (default) or dns. | | --json | Emit raw JSON. |

allyproof sites add https://example.com --name "Marketing site"
allyproof sites add https://example.com --name "Marketing site" --method dns --json

allyproof config

Inspect or modify the local CLI config.

allyproof config get                          # print everything
allyproof config get api_key                  # print one field
allyproof config set base_url https://allyproof.com
allyproof config set default_site_id 9b15692d-…
allyproof config path                         # show config file location

allyproof login / allyproof whoami

See Authenticate the CLI above.

CI gating

Two independent gates that can be combined — the build fails if either trips:

# Score gate — broad quality signal, tolerates a few small issues.
allyproof scan --site $SITE --threshold 80

# Severity gate — strict, fail if even one critical or serious finding lands.
allyproof scan --site $SITE --fail-on critical,serious

# Layered — score AND severity. Most teams end up here:
#   "score must be ≥ 80 AND no critical/serious findings."
allyproof scan --site $SITE --threshold 80 --fail-on critical,serious

--fail-on reads the per-severity counts in the scan summary, so a single critical issue across hundreds of minor advisories will fail the build. critical and serious are the two severities tied to ADA-cited rules in our litigation-risk model — most teams keep those at zero.

GitHub Actions

Score floor + zero-tolerance for critical/serious:

- name: Accessibility gate
  env:
    ALLYPROOF_API_KEY: ${{ secrets.ALLYPROOF_API_KEY }}
  run: |
    npx @allyproof/cli scan \
      --site ${{ vars.ALLYPROOF_SITE_ID }} \
      --threshold 80 \
      --fail-on critical,serious

SARIF output → GitHub code-scanning UI:

- name: Accessibility scan (SARIF)
  env:
    ALLYPROOF_API_KEY: ${{ secrets.ALLYPROOF_API_KEY }}
  run: |
    npx @allyproof/cli scan \
      --site ${{ vars.ALLYPROOF_SITE_ID }} \
      --output sarif > a11y.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: a11y.sarif
    category: allyproof

GitLab CI

a11y:
  image: node:20
  variables:
    ALLYPROOF_API_KEY: $ALLYPROOF_API_KEY
  script:
    - npx @allyproof/cli scan
      --site $ALLYPROOF_SITE_ID
      --threshold 80
      --fail-on critical,serious
      --output junit > a11y.junit.xml
  artifacts:
    when: always
    reports:
      junit: a11y.junit.xml

Environment variables

Recognised env vars (override the local config file):

| Variable | Purpose | |---|---| | ALLYPROOF_API_KEY | API key. Use this in CI so the key never lands on disk. | | ALLYPROOF_BASE_URL | Override the API base. Default: https://allyproof.com. | | ALLYPROOF_SITE_ID | Default site id for scan when no URL or --site is given. |

Exit codes

| Code | Meaning | |---|---| | 0 | Success. Scan ran AND every CI gate passed. | | 1 | Scan ran but at least one CI gate failed (--threshold not met OR a --fail-on severity present), OR a runtime error reached the top level (network blip, missing scan, server error). | | 2 | Invalid arguments / missing API key. | | 130 | Interactive login interrupted with Ctrl-C. |

Support

• Docs: allyproof.com/docs/cli
• Issues / questions: [email protected]

License

MIT. The full license text is bundled in the package tarball as LICENSE.