@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]	AI-powered audit summary, or evidence for a specific 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

AI Intelligence

Command	Description
suggest <intent>	Convert natural language to exact CLI command(s)
explain	AI-powered audit summary (also: evidence for a single finding)
triage	Prioritize findings into P0/P1/P2 buckets with effort estimates
fix-plan	Structured remediation plan with ordered steps
patch-review	Review a diff for safety (SAFE/UNSAFE/NEEDS_REVIEW verdict)
release-notes	Generate developer + PM release notes from audit diff
compare	Before/after audit narrative with score deltas (also: URL comparison)
doc	Generate a Team Playbook from recurring findings

All AI commands require authentication (vertaa login or VERTAAUX_API_KEY). They accept input via stdin pipe, --file, or --job.

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 (also supports --before/--after for LLM-powered comparison)

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
suggest	human, json	human
triage	human, json	human
fix-plan	human, json	human
patch-review	human, json	human
release-notes	human, json, markdown	markdown
compare	human, json	human
doc	json, markdown	markdown

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.3.3",
    "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

Pipeline Examples

Chain commands with Unix pipes for powerful workflows:

# Audit and get an AI-powered summary
vertaa audit https://example.com --json | vertaa explain

# Audit and explain with full evidence per issue
vertaa audit https://example.com --json | vertaa explain --verbose

# Audit, triage, and get a fix plan
vertaa audit https://example.com --json | vertaa triage --verbose
vertaa audit https://example.com --json | vertaa fix-plan --json

# Review a PR diff for safety against audit findings
gh pr diff 123 | vertaa patch-review --job <audit-job-id>

# Generate release notes from a diff between two audits
vertaa diff --job-a abc --job-b def --json | vertaa release-notes

# Compare two audit snapshots with LLM narrative
vertaa compare --before baseline.json --after current.json

# Convert natural language to a CLI command
vertaa suggest "check contrast on my site"

# Generate a team playbook from audit findings
vertaa audit https://example.com --json | vertaa doc --team "Frontend"

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
--color	Force colored output
--no-color	Disable colored output
--dashboard	Force live dashboard during audit --wait
--no-dashboard	Disable live dashboard (use spinner instead)
--dry-run	Show what would happen without executing
-y, --yes	Auto-confirm all interactive prompts
--verbose	Expand output with additional details
-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
VERTAAUX_AUTH_BASE	Auth endpoint override (default: https://vertaaux.ai)
VERTAAUX_LOG_LEVEL	Log verbosity: debug|info|warn|error (default: info)
VERTAAUX_LOG_JSON	Structured JSON logs (default: false)
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