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:

1. Environment variables (checked in order):

   • VERTAAUX_TOKEN
   • VERTAAUX_API_KEY

2. Stored credentials from interactive login:

   vertaa login

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

3. 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.4.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

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

1. .vertaaux.yml
2. .vertaaux.yaml
3. .vertaaux.json
4. vertaaux.config.js
5. vertaaux.config.mjs
6. vertaaux.config.cjs
7. 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