axe-core CLI — Complete Guide

In this tutorial, you will learn about axe. We cover key concepts, practical examples, and best practices to help you master this topic.

The axe-core CLI lets you run accessibility scans from the terminal using npx axe <url>, supporting rule configuration, tag filtering by WCAG level, and multiple output formats including JSON, CSV, and XLS for CI/CD integration.

What You'll Learn

You will install and configure axe-core CLI, scan pages with custom rule sets, filter by WCAG level, output results in different formats, and integrate scans into build scripts.

Why It Matters

CLI integration is essential for automated accessibility checks in CI/CD pipelines. Running axe-core from the command line means every deployment can be tested without manual effort, catching regressions before they reach production.

Real-World Use

A development team adds npx axe https://staging.example.com --exit to their deployment script. If the scan finds any violations, the deployment fails and the team gets notified in Slack. This ensures no accessibility regression ships to production.

CLI Workflow

flowchart TD
  A[Developer Push] --> B[CI Pipeline]
  B --> C[Build Site]
  C --> D[axe-core CLI Scan]
  D --> E{Violations?}
  E -->|Yes| F[Fail Build]
  E -->|No| G[Deploy]
  F --> H[Notify Team]
  H --> I[Fix and Re-push]

Installing and Running

Install axe-core CLI globally or use npx. The simplest scan runs against a single URL with default rules.

# Install globally
npm install -g @axe-core/cli

# Scan a URL
axe https://example.com

# Scan with exit code for CI
axe https://example.com --exit

You can configure which rules to run and which WCAG levels to check.

# Scan only WCAG AA rules
axe https://example.com --tags wcag2a,wcag2aa

# Save results as JSON
axe https://example.com --save results.json

# Scan with custom timeout for slow pages
axe https://example.com --timeout 30000

// Programmatic usage in Node.js scripts
const { analyze } = require('@axe-core/cli');

async function runAccessibilityScan(url) {
  try {
    const results = await analyze({
      url: url,
      tags: ['wcag2a', 'wcag2aa'],
      output: 'json'
    });
    console.log(`Violations: ${results.violations.length}`);
    results.violations.forEach(v => {
      console.log(`- ${v.help}`);
    });
  } catch (error) {
    console.error('Scan failed:', error);
  }
}

runAccessibilityScan('https://example.com');

Common Mistakes

• Not using the --exit flag in CI pipelines
• Running with default tags instead of project-specific WCAG levels
• Ignoring the --timeout option for single-page apps
• Not saving results for historical comparison
• Running scans on unauthenticated pages that require login
• Forgetting to update axe-core version regularly
• Not filtering out known, documented issues

Practice and Challenge

Practice 1: Install axe-core CLI and scan a public website. Practice 2: Run a scan with only WCAG AA rules and compare results. Practice 3: Save scan results as JSON and parse them with a script. Practice 4: Configure axe-core CLI to fail on any violation. Practice 5: Create a bash script that scans three URLs and reports pass/fail.

Challenge: Write a Node.js script that scans a list of URLs from a CSV file using axe-core CLI, collects all violations into a single report, and outputs a summary table showing pass/fail per URL.

FAQ

Mini Project

Create a GitHub Action workflow that runs axe-core CLI on every Pull Request against a staging URL, fails the check if violations are found, and posts the violation summary as a PR comment.

What's Next

axe-core with Cypress covers integrating axe-core into Cypress end-to-end tests.