@vertaaux/cli

VertaaUX CLI

Run UX and accessibility audits from the terminal or CI pipelines.

Install

npm install -g @vertaaux/cli

Or run with npx:

npx @vertaaux/cli --help

Quick Start

# 1. Authenticate
vertaa login

# 2. Run an audit
vertaa audit https://example.com --wait

# 3. Check CLI health
vertaa doctor

Authentication

The CLI checks for credentials in this order:

• Environment variables (checked in order):

  • VERTAAUX_TOKEN
  • VERTAAUX_API_KEY

• Stored credentials from interactive login:

  vertaa login
  

  Credentials are stored in ~/.vertaaux/credentials.json.

• Direct token for CI/non-interactive use:

  vertaa login --token <api-key>
  

Verify authentication:

vertaa whoami

Commands

Core Commands

Command	Description
audit <url>	Run UX and accessibility audit
baseline [job-id]	Create or update audit baseline
diff	Compare current audit against baseline
policy init|validate|show|schema	Manage policy-as-code

Analysis and Remediation

Command	Description
explain <finding-id>	Show evidence bundle for a finding
comment	Generate PR comment from audit results
fix <job-id>	Generate a fix patch for an issue
fix-all <job-id>	Generate fix patches for all issues
verify	Verify that a patch fixes an issue

Utility

Command	Description
doctor	Diagnose CLI health (config, auth, network)
login	Authenticate with VertaaUX
logout	Clear stored credentials
whoami	Show current authentication status
init	Create .vertaaux.yml configuration
status <job-id>	Check audit job status
upload <file>	Upload audit results to cloud storage
download <id>	Download audit results from cloud storage

Aliases

Command	Alias For
a11y <url>	Accessibility-focused audit (filters for a11y issues)
scan <url>	UX scan (alias for audit)
compare <urlA> <urlB>	Compare audits of two URLs

Output Formats

Formats are per-command, not global. Each command supports a different set of formats:

Command	Formats	Default
audit	human, json, sarif, junit, html	human
comment	json, markdown	markdown
explain	human, json	human
policy show	json, yaml	yaml
diff	human, json	human

Usage:

vertaa audit https://example.com --format json
vertaa audit https://example.com --format sarif > results.sarif
vertaa comment --input results.json --format markdown

Machine-Readable Output

The --machine global flag enables strict machine-readable mode:

• stdout: JSON data only (no banners, no diagnostics)
• stderr: All diagnostic and progress output
• JSON output is wrapped in an envelope:

{
  "meta": {
    "version": "0.1.0",
    "timestamp": "2026-02-08T12:00:00.000Z",
    "command": "audit",
    "args": ["https://example.com", "--format", "json"]
  },
  "data": {
    "scores": { "overall": 85 },
    "issues": []
  }
}

Piping

All diagnostic output goes to stderr, keeping stdout clean for piping:

vertaa audit https://example.com --format json | jq '.data.scores'
vertaa audit https://example.com --format json > results.json

Global Options

These options work with any command:

Option	Description
-b, --base <url>	API base URL override
-c, --config <path>	Explicit config file path
-q, --quiet	Suppress banner and non-essential output
--no-banner	Hide the V-mark banner
--machine	Strict machine-readable output mode
-v, --version	Show version number
-h, --help	Show help for command

Exit Codes

Code	Meaning	When
0	Success	Audit passed, no issues above threshold
1	Issues found	Issues at or above --fail-on severity
2	Error	Invalid input, validation errors, network failures
3	Threshold breach	Score below --threshold value

Exit code 2 is used for all validation errors, including:

• Invalid flag values (--timeout abc)
• Unknown enum values (--mode bogus)
• Missing required arguments

Configuration

The CLI uses cosmiconfig for configuration file auto-detection.

Config File Search Order

• .vertaaux.yml
• .vertaaux.yaml
• .vertaaux.json
• vertaaux.config.js
• vertaaux.config.mjs
• vertaaux.config.cjs
• package.json (vertaaux key)

Or specify explicitly:

vertaa audit https://example.com --config path/to/.vertaaux.yml

Configuration Precedence

flag > env var > config file > default

Key Config Fields

From VertaauxConfig interface in src/config/schema.ts:

Field	Type	Default	Description
mode	basic|standard|deep	basic	Audit depth
threshold	number	0	Minimum passing score (0-100)
failOn	error|warning|info	-	Fail on severity
output.format	auto|json|sarif|...	auto	Output format
output.groupBy	severity|category|route	severity	Issue grouping
baseline.path	string	.vertaaux/baseline.json	Baseline file path
baseline.autoUpdate	boolean	false	Auto-update baseline
ci.template	github|gitlab|...	none	CI template
timeout	number	60000	Audit timeout (ms)
interval	number	5000	Poll interval (ms)

Example Configuration

# .vertaaux.yml
$schema: https://vertaaux.ai/schemas/config.json

mode: standard
threshold: 80
failOn: error

output:
  format: auto
  groupBy: severity

baseline:
  path: .vertaaux/baseline.json
  autoUpdate: false

ci:
  template: github

timeout: 60000
interval: 5000

Create a starter configuration:

vertaa init
vertaa init --ci github --yes

Security

Branch Name Validation

Branch names passed via --base-branch and --branch flags are validated against an allowlist regex:

/^[a-zA-Z0-9._\/-]+$/

• Maximum length: 255 characters
• Shell metacharacters (;, |, $, `, etc.) are rejected
• Standard git branch names work as expected: main, feature/login, release/v1.2.3

Artifact Path Protection

Downloaded artifact filenames are validated to stay within the output directory:

• Path traversal attempts (../) are rejected with an error
• All artifact paths are resolved and checked against the target directory boundary
• This prevents writing to arbitrary filesystem locations

Credential Filtering

JSON envelope output automatically filters CLI arguments containing API keys or Bearer tokens from the args metadata field.

Environment Variables

Variable	Purpose
VERTAAUX_API_KEY	API authentication key
VERTAAUX_TOKEN	Alternative auth token (checked first)
VERTAAUX_API_BASE	API base URL override
NO_COLOR	Disable colored output
FORCE_COLOR	Force colored output

CI/CD Integration

GitHub Actions

- name: Run audit
  env:
    VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
  run: |
    npx @vertaaux/cli audit https://example.com \
      --format sarif \
      --fail-on error \
      --threshold 80

Exit Code Gating

# Fail CI if score below 80
vertaa audit https://example.com --threshold 80

# Fail CI if any error-severity issues found
vertaa audit https://example.com --fail-on error

# Both
vertaa audit https://example.com --threshold 80 --fail-on error

Error Messages

The CLI provides branded error messages with contextual help:

vertaa error: expected a number, got "abc"
  ──────────────────────────────────
  │ flag: --timeout
  │ value: abc
  │
  │ hint: Run vertaa <command> --help for all options
  ──────────────────────────────────

For enum values, typo suggestions are provided:

vertaa error: invalid value for --mode
  │ flag: --mode
  │ value: depp
  │
  │ hint: Did you mean "deep"?
  │ valid: basic, standard, deep

Related

• Migration Guide -- Breaking changes in this release
• Configuration Docs -- Full config reference
• CI/CD Integration -- Pipeline setup guides