a11ywatch-cli

The A11yWatch Command Line Interface. View the cli-docs for more complete info.

Installation

1. cargo install a11ywatch_cli

Optional:

If you are using Lite mode you can add the feature flag grpc to compile protoc and tonic.

Protoc is required to compile. Vendoring OpenSSL is available by using the feature flag dist-vendor upon install ex: cargo install --path . --features dist-vendor. The flag is also available following RTN Consuming for node installs via npm.

Linux

If you are on Ubuntu OpenSSL is required. You may need to add the command sudo before apt-get.

apt-get update && apt upgrade -y && apt-get install -y --no-install-recommends build-essential gcc cmake libc6 libssl-dev pkg-config

Windows

Cmake is required on windows.

Build

Get the CLI by running one of the commands below.

# install via cargo
cargo install a11ywatch_cli
# or install via npm
npm i a11ywatch-cli -g

Build init:

# build the instance first, this allows configuring architecture specifics like apple m1 chips.
a11ywatch build

Startup:

Use one of the following commands to start the instance. If you need the front-end client passing the -f option [min of 1.25gb of memory required alloc to docker resource].

# start the instance requires docker running.
a11ywatch start

# Start the instance with the front-end on port 3270 by default requires docker running..
a11ywatch start -f

# You can also start the system local via `nodejs` monolith.
a11ywatch start --local

# Use the `--standalone` flag to use the monolith in docker.
a11ywatch start --standalone

# If you need to upgrade the instance to new images run with the upgrade flag - can also be used with the build command.
a11ywatch start --upgrade

Actions:

# scan a url and pipe the stdout to a file.
a11ywatch scan --url https://a11ywatch.com > results.json
# scan a url and attempt to fix code based on recommendations [installs the fast ripgrep crate for search].
a11ywatch scan --url https://a11ywatch.com --fix
# scan and store results as csv to disk.
a11ywatch scan --save --csv --url https://a11ywatch.com
# scan a website multi page and pipe the stdout to a file.
a11ywatch crawl --url https://a11ywatch.com > results.json
# scan a website multi page and include subdomains.
a11ywatch crawl --url https://a11ywatch.com -S > results.json
# scan a website multi page and include subdomains and all TLD extensions.
a11ywatch crawl --url https://a11ywatch.com -S -t > results.json
# scan a website multi page and get results parsed as checklist.
a11ywatch crawl --url https://a11ywatch.com -d -n -s && a11ywatch --results-parsed-list
# crawl and store results as csv to disk.
a11ywatch crawl --save --csv --url https://a11ywatch.com

If you experience issues the cargo install a11ywatch_cli command, try running rustup update stable to make sure your cargo version is up to date.

ENV

Here are env vars that you can configure to enhance the system abilities. You can get your Computer Vision API key here. Grab your PageSpeed API key to speed up lighthouse parallel runs.

Example of a .env file below:

COMPUTER_VISION_SUBSCRIPTION_KEY="REPLACE_WITH_KEY"
COMPUTER_VISION_ENDPOINT="REPLACE_WITH_ENDPOINT"
PAGESPEED_API_KEY="REPLACE_WITH_PAGESPEED_API_KEY"
# set to a directory or true in order to enable recordings in litemode
PAGEMIND_RECORD=

You can also use the CLI to configure settings like Computer Vision creditials, Recording Video, and more.

# replace $mycv_token and $myvcvname with your project name and ComputerVision API url
a11ywatch --set-cv-token $mycv_token
a11ywatch --set-cv-url https://$myvcvname.cognitiveservices.azure.com/
a11ywatch --set-recording ./recordings

Example options and commands a11ywatch -h:

a11ywatch_cli 0.10.7
j-mendez <[email protected]>
A11yWatch web accessibility CLI.

USAGE:
    a11ywatch [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -c, --clear-token
            Clear the API token to use for requests

        --clear-cv-token
            Clear the Computer Vision API token to use for request

        --clear-recording
            Clear the recording preventing storing video

    -f, --find-results
            Log file results path

        --find-tmp-dir
            Get the apps tmp directory location

    -g, --github-api-url
            Get github API endpoint of project

        --github-results-path
            Log file results github path

    -h, --help
            Print help information

    -r, --results-parsed-list
            Get results file parsed as report list of passed / failed

    -R, --results-parsed
            Get results file parsed to json

        --results-issues
            Get the total amount of issues between errors,warning,notice that occurred for the
            result set

        --results-issues-errors
            Get the total amount of issues of type error from result set

        --results-issues-warnings
            Get the total amount of issues of type warning from result set

        --results-parsed-github
            Get results of the github html message

    -s, --set-token <SET_TOKEN>
            Set the API token to use for requests

        --set-cv-token <SET_CV_TOKEN>
            Set the Computer Vision API token to use for request

        --set-cv-url <SET_CV_URL>
            Set the Computer Vision API endpoint to use for request

        --set-recording <SET_RECORDING>
            Enable recording audits to a directory

    -V, --version
            Print version information

SUBCOMMANDS:
    build      Build A11yWatch Lite on the local machine [defaults to docker runtime]
    crawl      Site wide scan a website url for issues
    extract    Extract results in formats for platforms
    help       Print this message or the help of the given subcommand(s)
    scan       Single page scan a website url for issues
    start      Start A11yWatch Lite on the local machine [defaults to docker runtime]
    stop       Stop A11yWatch Lite on the local machine [defaults to docker runtime]

Supported Architectures

Mac, linux, and Windows.

Features

1. grpc - use gRPC to connect to the litemode instance.

Help

If you are trying to run a website that is running localhost inside a docker container you need to use your computers hostname instead.

In terminal run the command hostname and then you can use it ex: a11ywatch crawl --url $(hostname):3000.

In order to stop services make sure to pass in the proper flags that were used to build/start the instances.