CLI

@allyproof/cli is a single cross-platform binary for running scans, inspecting history, and gating CI/CD pipelines from your terminal. It wraps the public v1 REST API, so anything the dashboard can do, the CLI can script.

Install

Requires Node.js 20 or newer. Install globally for everyday use:

Shell

npm install -g @allyproof/cli

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

Shell

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

Authenticate

Generate an API key at Settings → API Keys. Keys are scoped to your organization and shown exactly once at creation — copy the value before closing the dialog.

Save the key locally with the interactive login command. It accepts the key on stdin (input hidden), verifies it against the server, and persists it to ~/.config/allyproof/config.json on POSIX (mode 0600) or %APPDATA%/allyproof/config.json on Windows.

Shell

allyproof login

For non-interactive shells (CI runners, containers, automation), export the key as an environment variable instead. The CLI prefers the env var over the saved config when both are present.

Shell

export ALLYPROOF_API_KEY=ap_live_…
allyproof whoami

whoami confirms the key authenticates and prints your organization, plan, and the scopes the key was granted.

Run your first scan

The simplest invocation takes a URL. The CLI looks up the matching tracked site in your account by hostname, queues a scan, waits for completion, and prints a summary.

Shell

allyproof scan https://example.com

For CI use, prefer --site <site-id>. It removes hostname-matching ambiguity when one URL legitimately maps to multiple environments — staging, preview, production — under separate tracked sites.

Shell

allyproof scan --site <site-id>

Or set ALLYPROOF_SITE_ID in the environment and call allyproof scan with no arguments. Useful when the same shell session always targets one site.

Two flags adjust the run itself:

--no-wait — enqueue a scan and return immediately with the scan id. Useful when wall-clock time matters more than the result.
--max-pages N— cap the page budget for this run. Helpful the first time you scan a large site so the run doesn't take an hour.

Inspect a scan

show displays per-page results plus the violations list for a single scan.

Shell

allyproof show <scan-id>

By default, show answers a specific question: what did this scan find that I still need to fix? The violations list is scoped to issues detected on this run with status open. Three flags widen the scope when you need a different question:

Flag	What it returns
`--include-resolved`	Issues this scan touched, including ones already resolved or dismissed.
`--include-history`	The entire site backlog, regardless of which scan saw what.
`--include-advisory`	Manual-review prompts (rules our scanner can't deterministically fail) added to the list.

The response always reports its scope as one of this_scan_open, this_scan_all, or site_history, so scripts never have to guess which view they're consuming.

Two count fields travel with every scan and are different on purpose. unique_issue_countis the number of distinct rules that fired (the headline number for “how many issues”); total_violations is the raw element-page occurrence count — a single rule firing on 14 elements across 5 pages is one issue but 70 occurrences. The pretty output shows both.

List past scans

historywalks the scans you've run, newest first.

Shell

allyproof history

Filter to a single site or status, and page through long lists with the cursor returned in each response.

Shell

allyproof history --site <site-id> --status completed --limit 50

Detect regressions between scans

diff compares two scans and reports what changed at the rule level: rules that newly appeared, rules whose page-coverage grew or shrank, and rules that disappeared because they were resolved.

Shell

allyproof diff <baseline-scan-id> <new-scan-id>

The exit code is 1if anything regressed, making this a clean CI gate for “don't merge if accessibility got worse since the last good build.”

Manage tracked sites

List the sites in your organization:

Shell

allyproof sites list

Register a new site programmatically. The response includes a verification token — paste the meta tag into your homepage <head> (or add the DNS TXT record) before the scanner can run a verified scan.

Shell

allyproof sites add https://example.com \
  --name "Example" \
  --method meta_tag

Use it in CI/CD

Two flags turn scan into a build gate. --threshold N fails when the resulting score drops below N. --fail-on critical,serious fails when any of the listed severities are present. Combine them for stricter gates.

Shell

allyproof scan https://staging.example.com \
  --threshold 80 \
  --fail-on critical,serious

Exit codes follow Unix convention: 0 means the gate passed, 1 means the scan succeeded but a gate failed, 2 means the invocation was invalid (typo in a flag, missing target, and similar).

GitHub Actions

Drop this into .github/workflows/accessibility.yml:

YAML

name: Accessibility
on: pull_request

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx -y @allyproof/cli scan https://staging.example.com --threshold 80 --fail-on critical
        env:
          ALLYPROOF_API_KEY: ${{ secrets.ALLYPROOF_API_KEY }}

For deeper integration with GitHub Code Scanning, emit SARIF and upload it — see the next section.

Output formats

Both scan and show accept --output. Pick the one your downstream tool consumes.

Format	When to use
`pretty` (default)	Humans reading a terminal. Colored, paginated, with hints.
`json`	Pipes cleanly into `jq` or any tool that parses JSON.
`sarif`	GitHub Code Scanning, Azure DevOps, GitLab. Hand the file to `github/codeql-action/upload-sarif`.
`junit`	Jenkins, CircleCI, Bamboo — anything consuming surefire-style XML.

For full-fidelity output (every violation, not just the top five), run scan --no-wait, wait for completion, then call show <scan-id> --output sarif. The scan-trigger response only carries a top-5 summary; the show endpoint returns everything.

Configuration

Three environment variables override the saved config when set:

Variable	Purpose
`ALLYPROOF_API_KEY`	Authentication. Beats the saved config so CI runners don't need a writable home dir.
`ALLYPROOF_BASE_URL`	API host. Defaults to `https://allyproof.com`; override only if you self-host.
`ALLYPROOF_SITE_ID`	Default site for `scan` when no URL or `--site` is passed.

Inspect the local config from the terminal:

Shell

allyproof config path
allyproof config get

get masks the API key so the output is safe to share during debugging.

Releases

Versions are tagged in the AllyProof repo as cli-vX.Y.Z and published to npm under the @allyproof scope. Pin a version in CI to keep builds reproducible:

Shell

npx -y @allyproof/cli@0.2.0 scan https://example.com

See the npm page for the full version history. Bug reports and feature requests belong on GitHub Issues.

Next steps

Set up a CI gate using the patterns in the CI/CD guide.
Browse the API referenceif you need calls the CLI doesn't expose yet.
Configure scheduled scans so the CLI stays for ad-hoc work, not nightly runs.