Skip to main content
Version: v5

Testing with the CLI

The AudioEye Accessibility Testing SDK CLI is the fastest way to run your first accessibility scan with the SDK. It is a good starting point if you want to:

  • verify that your entitlement token and package-manager configuration are working
  • scan a URL or local HTML without writing test code
  • scan local HTML exported from your app or design system
  • generate shareable HTML, JSON, or CSV output

Before you install​

Complete the entitlement-token and package-manager setup in getting started before installing the CLI.

The CLI package is distributed through AudioEye's private registry, so installation will fail until your project is configured to authenticate with that registry.

Prerequisites​

You will need:

  • Node.js 20, 22, or 24
  • an AudioEye entitlement token
  • a project configured to use npm, yarn, or pnpm
  • a browser environment available to the CLI when running scans

Installation​

Install the CLI as a development dependency in the project where you want to run scans.

npm install -D @audioeye/testing-sdk-cli

Verify the installation​

After installation, run a quick scan against a known page you can access. A deployed URL is one supported option, but it is not required.

npx aetest scan 'https://www.audioeye.com'

If this succeeds, you have confirmed that:

  • the package installed correctly
  • your entitlement token is configured correctly
  • the CLI can launch its browser environment
  • the CLI can analyze a page and write output

What the CLI can scan​

Use the CLI when you want to scan any of the following:

  • a reachable URL, including internal, staging, or deployed pages
  • a local HTML file
  • raw HTML passed over standard input
  • a component fragment, when used with component mode

Running the CLI​

Run the CLI with your package manager's local execution command.

npx aetest [command] [options]

First-run workflows​

Scan a reachable page by URL​

If you already completed the verification step above, you have done this. Otherwise, use the same command shown in that section to scan any reachable URL.

Escaping the URL

Wrapping the URL in single quotes helps avoid shell issues with special characters.

Scan a local HTML file through standard input​

Use this workflow if you already have exported HTML fixtures or a static HTML example.

npx aetest scan < example_inputs/document.html

Scan a local file by absolute path​

If you prefer, you can also point the CLI at a local file URL.

npx aetest scan "file://${PWD}/example_inputs/document.html"

Scan a component fragment​

By default, the CLI expects a complete HTML document. If you want to scan a component or fragment instead, use component mode.

For more details, see component vs full-page rules.

npx aetest scan --component < example_inputs/component.html

Understanding the output​

A typical scan prints a short summary to standard output and writes a detailed results file.

::: START AudioEye Accessibility Testing SDK CLI :::

Scanning HTML from STDIN
Rendered page content in 0.005 seconds
Running accessibility tests
Tests run in 0.1 seconds

AudioEye Rules Version: 11.1.1
Found 3 accessibility issues
   Img_Name_Missing - count: 3

Test results were written to aetest_output.html

::: END AudioEye Accessibility Testing SDK CLI :::

If you are new to the SDK, start by opening the HTML report that the CLI writes to disk. For a walkthrough of the available report formats and how to interpret them, see How Our Tests Work.

Output formats​

Use the --format flag to choose the output format:

  • html for a human-readable report
  • json for machine-readable output
  • csv for spreadsheet-style review

Example:

npx aetest scan --format json --output ./reports/a11y-results.json 'https://www.audioeye.com'

Common commands​

Show help​

npx aetest help

Describe a rule​

Use describe to inspect a specific rule and understand how it behaves.

npx aetest describe Img_Name_Missing

Use --print-test-list if you want to see which rules apply in the current scan context.

npx aetest scan --print-test-list 'https://www.audioeye.com'

Available commands​

scan [options] [url]  Perform an accessibility scan on a URL or on the provided raw HTML on stdin
describe [rule]       Output available information about the rules in the testing framework and their usage in the CLI
help [command]        Display help for command

Global options​

-V, --version         Output the version number
-h, --help            Display help for command

Scan options​

Usage: aetest scan [options] [url]

Perform an accessibility scan on a URL or on the provided raw HTML on stdin

Arguments:
  url                                         Optional URL to scan; if not provided, HTML is read from stdin

Options:
  -c, --component                             Run in component mode (create a document and inject the HTML)
  -p, --print-test-list                       Print the list of tests that will be run
  -d, --debug                                 Internal use only
  -f, --format <file_type>                    Define the output file type: html, json, or csv (default: "html")
  -o, --output <filename>                     Define the output file path; default is ./aetest_results.<file_type>
  -s, --stdout                                Output full results to stdout as well as a file
  -t, --timeout <seconds>                     Set the timeout for DOM rendering in seconds (default: "5")
  -v, --viewport-dimensions <width>x<height>  Set the browser viewport dimensions
  -m, --mobile                                Set the viewport to a mobile device; customize with --viewport-dimensions
  --css, --css-selectors                      Compute CSS selectors for elements with accessibility issues
  -h, --help                                  Display help for command

HTML report output​

After a scan completes, the CLI can write a detailed HTML report to disk.

Screenshot of an Accessibility Testing SDK CLI report highlighting issues found on an example webpage. A table provides detailed information on issue type, WCAG level, WCAG number, and additional details.

Running the CLI in Docker​

Running the CLI in Docker requires a browser environment. The simplest approach is to use the official Puppeteer Docker image, which includes Chrome and the required dependencies.

Use the official Puppeteer image as your base image.

Dockerfile
FROM ghcr.io/puppeteer/puppeteer:latest

When running the container, include the --cap-add=SYS_ADMIN flag so Chrome has the permissions it needs.

docker run --cap-add=SYS_ADMIN your-image-name

For more details, see the Puppeteer Docker docs and the Puppeteer troubleshooting guide.

When to use Playwright or Cypress instead​

The CLI is best for quick scans of a page URL or local HTML. It does not support cookies or authenticated flows.

If you need to test login flows, maintain session state, or validate multi-step browser journeys, use:

Troubleshooting​

Installation fails​

If installation fails, first verify that you completed the token and registry setup in getting started.

Common causes include:

  • the entitlement token is missing or expired
  • the token is not exposed as AUDIOEYE_ENTITLEMENT_TOKEN
  • .npmrc or .yarnrc.yml is missing the @audioeye registry configuration
  • the install is running in CI without the required secret configured

You can also review the broader Troubleshooting guide.

Browser launch issues​

If the CLI installs successfully but scans fail at runtime, check that the environment can launch Chrome or Chromium successfully. This is especially common in:

  • Docker containers
  • minimal Linux images
  • locked-down CI environments

In those cases, start with the Docker guidance above and make sure the required browser dependencies are available.

No results for component HTML​

If you are scanning a fragment instead of a full HTML document, retry with --component. Some rules only apply in full-page contexts, so also review About Our Rules.