CLI

@allyproof/cli ist eine einzige plattformübergreifende Binärdatei zum Ausführen von Scans, Einsehen des Verlaufs und Absichern von CI/CD-Pipelines vom Terminal aus. Sie umschließt die öffentliche v1-REST-API – alles, was das Dashboard kann, kann die CLI skripten.

Installation

Erfordert Node.js 20 oder neuer. Für den täglichen Gebrauch global installieren:

npm install -g @allyproof/cli

Oder in CI über npx ausführen, um eine dauerhafte Installation zu vermeiden:

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

Authentifizieren

Erstellen Sie einen API-Schlüssel unter Einstellungen → API-Schlüssel. Schlüssel sind auf Ihre Organisation beschränkt und werden bei der Erstellung genau einmal angezeigt – kopieren Sie den Wert, bevor Sie den Dialog schließen.

Speichern Sie den Schlüssel lokal mit dem interaktiven Login-Befehl. Er nimmt den Schlüssel über stdin entgegen (Eingabe verborgen), verifiziert ihn gegen den Server und speichert ihn unter ~/.config/allyproof/config.json auf POSIX (Modus 0600) oder %APPDATA%/allyproof/config.json unter Windows.

allyproof login

Exportieren Sie für nicht interaktive Shells (CI-Runner, Container, Automatisierung) den Schlüssel stattdessen als Umgebungsvariable. Die CLI bevorzugt die Umgebungsvariable gegenüber der gespeicherten Konfiguration, wenn beide vorhanden sind.

export ALLYPROOF_API_KEY=ap_live_…
allyproof whoami

whoami bestätigt, dass der Schlüssel authentifiziert, und gibt Ihre Organisation, Ihren Plan und die dem Schlüssel gewährten Scopes aus.

Ihren ersten Scan ausführen

Der einfachste Aufruf nimmt eine URL entgegen. Die CLI sucht die passende verfolgte Website in Ihrem Konto nach Hostname, reiht einen Scan ein, wartet auf den Abschluss und gibt eine Zusammenfassung aus.

allyproof scan https://example.com

Bevorzugen Sie für CI-Nutzung --site <site-id>. Das entfernt die Hostname-Abgleich-Mehrdeutigkeit, wenn eine URL legitim auf mehrere Umgebungen abbildet – Staging, Preview, Produktion – unter separaten verfolgten Websites.

allyproof scan --site <site-id>

Oder setzen Sie ALLYPROOF_SITE_ID in der Umgebung und rufen Sie allyproof scan ohne Argumente auf. Nützlich, wenn dieselbe Shell-Sitzung immer eine Website anvisiert.

Zwei Flags passen den Lauf selbst an:

• --no-wait – reiht einen Scan ein und kehrt sofort mit der Scan-ID zurück. Nützlich, wenn die Echtzeit-Dauer wichtiger ist als das Ergebnis.
• --max-pages N – begrenzt das Seitenbudget für diesen Lauf. Hilfreich beim ersten Scan einer großen Website, damit der Lauf nicht eine Stunde dauert.

Einen Scan einsehen

show zeigt Ergebnisse pro Seite sowie die Verstoßliste für einen einzelnen Scan.

allyproof show <scan-id>

Standardmäßig beantwortet show eine bestimmte Frage: was hat dieser Scan gefunden, das ich noch beheben muss? Die Verstoßliste ist auf in diesem Lauf erkannte Probleme mit Status open beschränkt. Drei Flags erweitern den Umfang, wenn Sie eine andere Frage brauchen:

Die Antwort meldet ihren Umfang immer als einen von this_scan_open, this_scan_all oder site_history, sodass Skripte nie raten müssen, welche Ansicht sie konsumieren.

Zwei Zählfelder begleiten jeden Scan und sind absichtlich unterschiedlich. unique_issue_count ist die Anzahl der distinkten ausgelösten Regeln (die Schlagzeilenzahl für "wie viele Probleme"); total_violations ist die rohe Element-Seite-Vorkommenszahl – eine einzelne Regel, die auf 14 Elementen über 5 Seiten auslöst, ist ein Problem, aber 70 Vorkommen. Die formatierte Ausgabe zeigt beide.

Vergangene Scans auflisten

history geht Ihre bisherigen Scans durch, neueste zuerst.

allyproof history

Filtern Sie nach einer einzelnen Website oder einem Status und blättern Sie mit dem in jeder Antwort zurückgegebenen Cursor durch lange Listen.

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

Regressionen zwischen Scans erkennen

diff vergleicht zwei Scans und meldet, was sich auf Regel-Ebene geändert hat: neu aufgetauchte Regeln, Regeln, deren Seitenabdeckung gewachsen oder geschrumpft ist, und Regeln, die verschwunden sind, weil sie behoben wurden.

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

Der Exit-Code ist 1, wenn sich etwas verschlechtert hat, was dies zu einem sauberen CI-Gate für "nicht mergen, wenn die Barrierefreiheit seit dem letzten guten Build schlechter geworden ist" macht.

Verfolgte Websites verwalten

Listen Sie die Websites in Ihrer Organisation auf:

allyproof sites list

Registrieren Sie eine neue Website programmatisch. Die Antwort enthält ein Verifikationstoken – fügen Sie das Meta-Tag in den <head> Ihrer Startseite ein (oder fügen Sie den DNS-TXT-Eintrag hinzu), bevor der Scanner einen verifizierten Scan ausführen kann.

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

--name ist erforderlich. --method ist standardmäßig meta_tag; übergeben Sie --method dns, um stattdessen per DNS-TXT-Eintrag zu verifizieren.

Einen Scan im Browser öffnen

allyproof open <scan-id> öffnet die Scan-Seite in Ihrem Standardbrowser. In CI-/Headless-Umgebungen, wo das Öffnen eines Browsers keinen Sinn ergibt, übergeben Sie --print, um stattdessen die URL nach stdout zu schreiben – nützlich, um sie in eine Slack-Benachrichtigung oder einen PR-Kommentartext zu leiten.

allyproof open <scan-id>
allyproof open <scan-id> --print  # in CI: URL für eine Benachrichtigung erfassen

In CI/CD verwenden

Zwei Flags machen aus scan ein Build-Gate. --threshold N schlägt fehl, wenn der resultierende Score unter N fällt. --fail-on critical,serious schlägt fehl, wenn einer der aufgelisteten Schweregrade vorhanden ist. Kombinieren Sie beide für strengere Gates.

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

Exit-Codes folgen der Unix-Konvention:

• 0 – Erfolg. Scan lief UND jedes CI-Gate bestand.
• 1 – Scan lief, aber mindestens ein CI-Gate ist fehlgeschlagen (--threshold nicht erreicht ODER ein --fail-on-Schweregrad vorhanden), ODER ein Laufzeitfehler erreichte die oberste Ebene (Netzwerkaussetzer, fehlender Scan, Serverfehler).
• 2 – ungültige Argumente / fehlender API-Schlüssel.
• 130 – interaktiver login mit Strg-C unterbrochen.

GitHub Actions

Legen Sie dies unter .github/workflows/accessibility.yml ab:

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 }}

Für tiefere Integration mit GitHub Code Scanning geben Sie SARIF aus und laden es über github/codeql-action/upload-sarif hoch:

- name: Accessibility scan (SARIF)
  env:
    ALLYPROOF_API_KEY: ${{ secrets.ALLYPROOF_API_KEY }}
  run: |
    npx -y @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

Befunde erscheinen im Security → Code scanning-Tab des Repos, neben CodeQL und anderen Scannern.

GitLab CI

Geben Sie JUnit-XML aus und lassen Sie GitLab es als regulären Testbericht an die Merge-Request-Ansicht anhängen:

a11y:
  image: node:20
  variables:
    ALLYPROOF_API_KEY: $ALLYPROOF_API_KEY
  script:
    - npx -y @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

Ausgabeformate

Sowohl scan als auch show akzeptieren --output. Wählen Sie das Format, das Ihr nachgelagertes Tool konsumiert.

Führen Sie für Ausgabe mit voller Genauigkeit (jeder Verstoß, nicht nur die Top 5) scan --no-wait aus, warten Sie auf den Abschluss und rufen Sie dann show <scan-id> --output sarif auf. Die Scan-Auslöse-Antwort trägt nur eine Top-5-Zusammenfassung; der show-Endpunkt gibt alles zurück.

Konfiguration

Drei Umgebungsvariablen überschreiben die gespeicherte Konfiguration, wenn gesetzt:

Prüfen Sie die lokale Konfiguration vom Terminal aus:

allyproof config path
allyproof config get

get maskiert den API-Schlüssel, sodass die Ausgabe beim Debuggen sicher geteilt werden kann.

Releases

Versionen werden unter dem @allyproof-Scope auf npm veröffentlicht. Binden Sie in CI eine Version fest, um reproduzierbare Builds zu erhalten:

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

Die vollständige Versionshistorie finden Sie auf der npm-Seite. Für Fehlermeldungen und Funktionswünsche schreiben Sie an support@allyproof.com.

Nächste Schritte

• Richten Sie ein CI-Gate mit den Mustern in der CI/CD-Anleitung ein.
• Durchstöbern Sie die API-Referenz, falls Sie Aufrufe brauchen, die die CLI noch nicht bietet.
• Konfigurieren Sie geplante Scans, damit die CLI für Ad-hoc-Arbeit reserviert bleibt, nicht für nächtliche Läufe.