Installation

Install the VertaaUX CLI via npm or npx and configure authentication for UX auditing

Install the VertaaUX CLI using your preferred method.

Installation Methods

Install globally for persistent access:

$npm install -g @vertaaux/cli

Verify installation:

$vertaa --version

0.5.0

Project-local Installation

For CI/CD or team consistency, install as a dev dependency:

npm install --save-dev @vertaaux/cli

Then run via npx or npm scripts.

Run directly without installing:

$npx @vertaaux/cli audit -u https://example.com

This downloads and runs the latest version each time. Best for one-off usage or trying out the CLI.

npx adds a small startup delay while it checks for updates. For frequent use, global installation is faster.

System Requirements

Node.js 20+ (tested on Node 20 and 22)
Operating Systems: macOS, Linux, Windows

Authentication

After installation, authenticate with your VertaaUX account.

$vertaa login

Enter your API key when prompted. See Getting an API Key.

Credentials are stored in ~/.vertaaux/credentials.json. The CLI reads this file automatically as a fallback when neither the VERTAAUX_API_KEY environment variable nor config file apiKey is set.

Option 2: Environment Variable

Set VERTAAUX_API_KEY in your environment:

export VERTAAUX_API_KEY=vx_live_your_key_here

Add to ~/.bashrc or ~/.zshrc for persistence.

set VERTAAUX_API_KEY=vx_live_your_key_here

For persistence, use System Properties > Environment Variables.

$env:VERTAAUX_API_KEY = "vx_live_your_key_here"

CI/CD Environments

In CI/CD, always use the environment variable method. Store your API key in your CI provider's secrets management (GitHub Secrets, GitLab CI Variables, etc.).

Option 3: Configuration File

Add your API key to .vertaaux.yml:

apiKey: vx_live_your_key_here  # Not recommended - use env var instead

Security Warning

Avoid committing API keys to version control. Use environment variables or your CI provider's secrets management.

Verify Setup

Check that everything is working:

$vertaa whoami

Authenticated as: your-email@example.com
Plan: Pro
Credits remaining: 950/1000

If you see your account details, you're ready to run audits.

Proxy Configuration

If you're behind a corporate proxy:

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
vertaa audit -u https://example.com

Updating

$npm update -g @vertaaux/cli

Uninstalling

$npm uninstall -g @vertaaux/cli

Optionally, remove stored credentials:

rm -rf ~/.vertaaux

Troubleshooting

"command not found: vertaa"

Cause: The CLI is not in your PATH.

Solutions:

For npm global installs, ensure npm's global bin directory is in your PATH:

npm config get prefix  # Shows npm prefix
export PATH="$(npm config get prefix)/bin:$PATH"

"Unauthorized" or "Invalid API key"

Cause: Missing or invalid authentication.

Solutions:

Run vertaa doctor to diagnose auth status
Run vertaa login and re-enter your API key
Verify you created the right key in API Authentication
Check that VERTAAUX_API_KEY environment variable is set correctly

"EACCES: permission denied"

Cause: npm lacks permissions to write to global directory.

Solutions:

Use a Node version manager (nvm, fnm) which doesn't require sudo
Or fix npm permissions: npm docs

Quickstart - Run your first audit
Configuration - Configure defaults with .vertaaux.yml
API Authentication - How authentication works

Was this page helpful?

Installation

On this page