Interface en ligne de commande

@allyproof/cli est un binaire multiplateforme unique, destiné à lancer des analyses, consulter l'historique et conditionner vos chaînes CI/CD depuis le terminal. Il enveloppe l'API REST publique v1 : tout ce que fait le tableau de bord peut donc être scripté.

Business inclut les clés d'API, la CLI, les outils MCP authentifiés et l'intégration CI/CD. Les propriétaires et administrateurs de l'organisation peuvent créer des clés. Free n'inclut pas les clés d'API ; l'outil MCP public scan_url reste disponible sans clé.

Installer

Node.js 20 ou une version plus récente est nécessaire. Installez l'outil globalement pour un usage quotidien :

npm install -g @allyproof/cli

Ou exécutez-le via npx dans votre chaîne d'intégration, pour éviter une installation permanente :

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

S'authentifier

Générez une clé d'API dans Réglages → Clés d'API. Les clés sont limitées à votre organisation et affichées une seule fois, à la création : copiez la valeur avant de fermer la fenêtre.

Enregistrez la clé localement avec la commande de connexion interactive. Elle accepte la clé sur l'entrée standard - la saisie est masquée -, la vérifie auprès du serveur, puis l'enregistre dans ~/.config/allyproof/config.json sur les systèmes POSIX (mode 0600) ou dans %APPDATA%/allyproof/config.json sous Windows.

allyproof login

Pour les interpréteurs non interactifs - exécuteurs d'intégration continue, conteneurs, automatisations -, exportez plutôt la clé dans une variable d'environnement. L'outil privilégie la variable d'environnement sur la configuration enregistrée lorsque les deux sont présentes.

export ALLYPROOF_API_KEY=ap_live_…
allyproof whoami

whoami confirme que la clé s'authentifie, et affiche votre organisation, votre offre et les portées accordées à la clé.

Lancer votre première analyse

L'appel le plus simple prend une URL. L'outil recherche dans votre compte, par nom d'hôte, le site suivi correspondant, met une analyse en file d'attente, attend son achèvement et affiche un récapitulatif.

allyproof scan https://example.com

Dans une chaîne d'intégration, préférez --site <site-id> : cela supprime toute ambiguïté de correspondance par nom d'hôte lorsqu'une même URL renvoie légitimement à plusieurs environnements - préproduction, prévisualisation, production - suivis comme des sites distincts.

allyproof scan --site <site-id>

Vous pouvez aussi définir ALLYPROOF_SITE_ID dans l'environnement et appeler allyproof scan sans argument. Pratique lorsqu'une même session vise toujours le même site.

Deux options ajustent l'exécution elle-même :

• --no-wait : met une analyse en file d'attente et rend la main immédiatement, avec l'identifiant de l'analyse. Utile lorsque le temps écoulé importe plus que le résultat.
• --max-pages N : plafonne le budget de pages pour cette exécution. Utile la première fois que vous analysez un grand site, pour que l'exécution ne dure pas une heure.

Examiner une analyse

show affiche les résultats page par page ainsi que la liste des non-conformités d'une analyse.

allyproof show <scan-id>

Par défaut, show répond à une question précise : qu'a trouvé cette analyse qu'il me reste à corriger ? La liste des non-conformités se limite aux problèmes détectés lors de cette exécution et dont le statut est open. Trois options élargissent la portée lorsque la question change :

La réponse indique toujours sa portée - this_scan_open, this_scan_all ou site_history -, afin qu'un script n'ait jamais à deviner la vue qu'il consomme.

Deux décomptes accompagnent chaque analyse, et ils diffèrent à dessein. unique_issue_count est le nombre de règles distinctes déclenchées - le chiffre de référence pour « combien de problèmes » ; total_violations est le nombre brut d'occurrences élément-page : une règle déclenchée sur 14 éléments répartis sur 5 pages représente un problème, mais 70 occurrences. La sortie lisible affiche les deux.

Lister les analyses passées

history parcourt les analyses que vous avez lancées, de la plus récente à la plus ancienne.

allyproof history

Filtrez par site ou par statut, et parcourez les longues listes avec le curseur renvoyé dans chaque réponse.

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

Détecter les régressions entre deux analyses

diff compare deux analyses et indique ce qui a changé au niveau des règles : règles nouvellement apparues, règles dont la couverture de pages s'est étendue ou réduite, et règles disparues parce qu'elles ont été corrigées.

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

Le code de sortie vaut 1 en cas de régression, ce qui en fait un contrôle d'intégration net pour « ne pas fusionner si l'accessibilité s'est dégradée depuis la dernière construction satisfaisante ».

Gérer les sites suivis

Lister les sites de votre organisation :

allyproof sites list

Enregistrer un nouveau site par programme. La réponse comporte un jeton de vérification : collez la balise méta dans le <head> de votre page d'accueil, ou ajoutez l'enregistrement DNS TXT, avant que l'analyseur puisse lancer une analyse vérifiée.

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

--name est obligatoire. --method vaut meta_tag par défaut ; passez --method dns pour une vérification par enregistrement DNS TXT.

Ouvrir une analyse dans le navigateur

allyproof open <scan-id> ouvre la page de l'analyse dans votre navigateur par défaut. Dans un environnement d'intégration continue ou sans interface, où lancer un navigateur n'a pas de sens, passez --print pour écrire l'URL sur la sortie standard - utile pour alimenter une notification Slack ou le corps d'un commentaire de demande de fusion.

allyproof open <scan-id>
allyproof open <scan-id> --print  # en CI : récupérer l'URL pour une notification

L'utiliser en CI/CD

Deux options transforment scan en contrôle de construction. --threshold N fait échouer l'exécution lorsque le score obtenu passe sous N. --fail-on critical,serious la fait échouer dès que l'une des gravités listées est présente. Combinez-les pour un contrôle plus strict.

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

Les codes de sortie suivent la convention Unix :

• 0 - succès. L'analyse s'est exécutée ET tous les contrôles d'intégration sont satisfaits.
• 1 - l'analyse s'est exécutée mais au moins un contrôle a échoué (--threshold non atteint OU une gravité de --fail-on présente), OU une erreur d'exécution a remonté jusqu'au niveau supérieur (coupure réseau, analyse introuvable, erreur serveur).
• 2 - arguments invalides ou clé d'API absente.
• 130 - commande login interactive interrompue par Ctrl-C.

GitHub Actions

À placer dans .github/workflows/accessibility.yml :

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

Pour une intégration plus poussée avec GitHub Code Scanning, produisez un fichier SARIF et téléversez-le via github/codeql-action/upload-sarif :

- 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

Les résultats apparaissent dans l'onglet Security → Code scanning du dépôt, aux côtés de CodeQL et des autres analyseurs.

GitLab CI

Produisez un fichier JUnit XML et laissez GitLab le rattacher à la vue de la demande de fusion comme un rapport de test ordinaire :

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

Formats de sortie

scan comme show acceptent --output. Retenez celui que consomme votre outil en aval.

Pour une sortie complète - toutes les non-conformités, et non les cinq principales -, lancez scan --no-wait, attendez l'achèvement, puis appelez show <scan-id> --output sarif. La réponse au déclenchement d'une analyse ne porte qu'un récapitulatif des cinq premières ; le point d'accès show renvoie tout.

Configuration

Trois variables d'environnement l'emportent sur la configuration enregistrée lorsqu'elles sont définies :

Pour examiner la configuration locale depuis le terminal :

allyproof config path
allyproof config get

get masque la clé d'API : la sortie peut donc être partagée sans risque lors d'un diagnostic.

Versions

Les versions sont publiées sur npm sous la portée @allyproof. Figez une version dans votre chaîne d'intégration pour des constructions reproductibles :

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

Voir la page npm pour l'historique complet des versions. Pour signaler une anomalie ou demander une fonctionnalité, écrivez à support@allyproof.com.

Pour aller plus loin

• Mettez en place un contrôle d'intégration en suivant les schémas du guide CI/CD.
• Parcourez la référence de l'API si vous avez besoin d'appels que l'outil n'expose pas encore.
• Configurez les analyses planifiées, afin que l'outil en ligne de commande reste réservé au travail ponctuel plutôt qu'aux exécutions nocturnes.