@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).

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.

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.

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.

allyproof diff abc123… def456…

allyproof open <scanId>

Open the scan in the AllyProof dashboard in your default 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.

allyproof sites add <url>

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

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):

Exit codes

Support

• Docs: allyproof.com/docs/cli
• Issues / questions: support@allyproof.com

License

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