Configuring Axe DevTools for Web CLI

The flags described in this article are available for axe <url>, axe spec, and axe bulk-spec. When you set one of these flags, the value is saved to the preferences file and becomes the default for all subsequent runs. To view or change preferences interactively, including resetting values that have no corresponding flag, use axe config-selenium.

Browser Options

--accept-untrusted

Instructs the browser to accept untrusted SSL certificates. Use this when testing pages on local development servers or internal environments that use self-signed certificates. Passing this flag saves acceptUntrustedCertificates: true to the preferences file. To reset it to false, run axe config-selenium and answer No when prompted, or edit the preferences file directly.

axe <url> --accept-untrusted

--browser <name>

Specifies which browser to use. The corresponding WebDriver must be installed and available on your $PATH. Valid values are: firefox (default), chrome, safari, edge, ie.

axe <url> --browser chrome

--headless

Launches the browser in headless mode (no visible window). The default is false.

axe <url> --headless

--remote-server <url>

Connects to a remote WebDriver server instead of launching a local browser. The server must expose a W3C WebDriver-compatible endpoint, such as a Selenium Grid, BrowserStack, or Sauce Labs remote.

axe <url> --remote-server https://hub.browserstack.com/wd/hub

--window-size <width,height>

Sets the browser window size in pixels. This also controls the viewport size in headless mode, making it useful for testing responsive layouts.

axe <url> --window-size 1280,900

Timing Options

--page-timeout <ms>

Maximum time in milliseconds (ms) to wait for a page to load before failing. Default is 60,000 ms (60 seconds). Increase this for slow-loading pages or network environments with high latency.

axe <url> --page-timeout 120000

--post-analyze-pause <ms>

Time in milliseconds to pause after completing an analysis before moving to the next action in a workflow. Default is 2,000 ms (2 seconds).

axe spec workflow.yml --post-analyze-pause 5000

--post-get-pause <ms>

Time in milliseconds to pause after loading a page and before starting the scan. Default is 2,000 ms (2 seconds). Increase this if dynamic content needs more time to render before scanning begins.

axe <url> --post-get-pause 5000

--post-script-pause <ms>

Time in milliseconds to pause after executing a workflow script action and before continuing to the next action. Default is 2,000 ms (2 seconds).

axe spec workflow.yml --post-script-pause 5000

--script-timeout <ms>

Maximum time in milliseconds to wait for a workflow script to finish executing. Default is 60,000 ms (60 seconds).

axe spec workflow.yml --script-timeout 120000

Usage Tracking

Axe DevTools CLI includes the @deque/metrics-library, which sends anonymous usage data to Deque. This data includes aggregate information such as violation counts, rule counts, and axe-core engine version. It does not include URLs, page content, or any personally identifiable information.

A distinct ID is a value stored in the preferences file used to correlate events across multiple CLI runs without identifying the user. You can change or disable tracking with the options below. To disable tracking entirely without using the CLI, set the environment variable AXE_TRACK_USAGE=false.

--enable-tracking <state>

Enables or disables sending usage data to the metrics library. Pass true to enable or false to disable.

axe <url> --enable-tracking false

--set-distinct-id <id>

Changes the distinct ID used to correlate usage events. The ID is stored in the preferences file and used across runs.

axe <url> --set-distinct-id my-team-id

--set-tracking-url <url>

Changes the endpoint where usage metrics are sent. Use this if your organization routes telemetry through an internal proxy.

axe <url> --set-tracking-url https://metrics.example.com/collect

axe config-selenium

Use axe config-selenium to configure defaults interactively. You will be prompted to enter values for browser, timeout, and other settings. Your answers are saved to the preferences file and become the defaults for all subsequent CLI runs.

$ axe config-selenium
? Choose browser for running automated tests: (Use arrow keys)
? Choose browser for running automated tests: chrome
? Enter a value for pageLoadTimeout: 60000
? Enter a value for setScriptTimeout: 60000
? Accept untrusted ssl certs: Yes
? Enter a value for postGetPause: 2000
? Enter a value for postScriptPause: 2000
? Enter a value for postAnalysisPause: 2000
? Launch browser in headless mode: No

Results saved to ~/.config/preferences/com.deque.axe.devtools.cli.pref

To view the current saved settings without entering the interactive prompt, use the --show flag:

axe config-selenium --show

Preferences File

All configurable defaults are stored in a JSON file at:

~/.config/preferences/com.deque.axe.devtools.cli.pref

A typical file looks like this:

{
  "selenium": {
    "acceptUntrustedCertificates": false,
    "browser": "firefox",
    "headless": false,
    "pageLoadTimeout": 60000,
    "postAnalysisPause": 2000,
    "postGetPause": 2000,
    "postScriptPause": 2000,
    "setScriptTimeout": 60000
  }
}

You can edit this file directly as an alternative to using axe config-selenium or passing flags on the command line. This is useful for resetting boolean values like acceptUntrustedCertificates without running the interactive prompt.