Run accessibility checks using the CLI

Use the Accessibility DevTools Command Line Interface (CLI) to automate accessibility checks in your development workflow.

The Accessibility DevTools CLI enables you to scan your codebase for accessibility issues directly from the terminal. This is useful for integrating accessibility testing into CI/CD pipelines or running checks locally without a UI.

With the CLI, you can scan multiple files or entire directories at once, and add accessibility as a quality check to your Git commits or CI/CD builds. This helps you catch issues early and maintain accessibility standards throughout your development workflow.

Install the CLI

curl -L "https://api.browserstack.com/sdk/v1/download_cli?os=macos&os_arch=arm64" | bsdtar -xvf- -O > browserstack-cli && chmod 0775 browserstack-cli

curl -L "https://api.browserstack.com/sdk/v1/download_cli?os=macos&os_arch=x64" | bsdtar -xvf- -O > browserstack-cli && chmod 0775 browserstack-cli

curl -L "https://api.browserstack.com/sdk/v1/download_cli?os=linux&os_arch=arm64" | tar -xz -O > browserstack-cli && chmod +x browserstack-cli

curl -L "https://api.browserstack.com/sdk/v1/download_cli?os=linux&os_arch=x64" | tar -xz -O > browserstack-cli && chmod +x browserstack-cli

curl -L "https://api.browserstack.com/sdk/v1/download_cli?os=alpine&os_arch=arm64" | tar -xz -O > browserstack-cli && chmod +x browserstack-cli

Invoke-WebRequest -Uri "https://api.browserstack.com/sdk/v1/download_cli?os=windows&os_arch=x64" -OutFile browserstack_cli.zip
Expand-Archive -Path browserstack_cli.zip -DestinationPath . -Force
Rename-Item -Path "binary-win-x64.exe" -NewName "browserstack-cli.exe"
Remove-Item browserstack_cli.zip  # Cleanup

Authenticate with your BrowserStack account

1. Log in to your BrowserStack account or sign up if you don’t have an account.

2. Obtain your Username and Access Key from the Account & Profile section section on the dashboard.

3. Set the following environment variables using the Username and Access Key you obtained in step 2. This allows the CLI to authenticate with your BrowserStack account:
   • BROWSERSTACK_USERNAME
   • BROWSERSTACK_ACCESS_KEY

   Add the export commands to the configuration file, depending on your shell:

   • Zsh: Add the following lines to your ~/.zshrc file:

     export BROWSERSTACK_USERNAME=YOUR_USERNAME
     export BROWSERSTACK_ACCESS_KEY=YOUR_ACCESS_KEY
     

   • Bash: Add the following lines to your ~/.bashrc or ~/.bash_profile file:

     export BROWSERSTACK_USERNAME=YOUR_USERNAME
     export BROWSERSTACK_ACCESS_KEY=YOUR_ACCESS_KEY
     

   • Fish Shell: Add the following lines to your ~/.config/fish/config.fish file:

     set -x BROWSERSTACK_USERNAME YOUR_USERNAME
     set -x BROWSERSTACK_ACCESS_KEY YOUR_ACCESS_KEY
     

   After updating your configuration file, restart your terminal or run source on the file to apply the changes.

Run accessibility checks

To scan your files or directories for accessibility issues, use the following command:

./browserstack-cli accessibility --include src/**.jsx 

This command scans all .jsx files in the src directory and its subdirectories for accessibility issues.

CLI options

You can use the following options with the CLI:

Scope checks to changed code only

By default, the CLI scans every file matched by --include and --exclude. If you want to check only the code you’ve actually changed, for example in a pre-commit hook or a PR check, use --scope=diff:

--scope=diff requires your project to be a git repository. If no .git directory is found, the CLI exits with code 2 and an error message.

Local mode without the --base flag

When you run the command without --base, --scope=diff checks your staged changes, the same content that would be included if you ran git commit right now. Behavior depends on your working tree state:

If you have unstaged changes you want included, stage them with git add before you run the check.

CI mode with the --base flag

In CI, use --base to scope the scan to everything changed relative to a branch or commit, rather than your local staged changes:

This is useful for PR checks where you want to flag only the issues introduced by the PR, not pre-existing issues elsewhere in the codebase.

How pre-existing issues on changed lines are handled

If you edit a line that already had an accessibility issue, the CLI reports that issue. You’re responsible for lines you touch, even if you didn’t introduce the original issue. However, the command still exits 0 as long as your change didn’t introduce any new issues. It doesn’t fail your commit or PR purely because of pre-existing issues on lines you touched, only for issues that are new.

Exit codes

The CLI returns the following exit codes:

Sample pre-commit hook to run accessibility checks

You can use the following script to run accessibility checks automatically before each commit. Add this script to your repository’s .git/hooks/pre-commit file:

Sample script using --scope=diff

For faster pre-commit checks, scope the scan to only the changes you’re about to commit instead of your entire codebase:

This checks only the files and lines you’ve staged, so the hook stays fast even on large codebases.