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

# Try it now — no account needed (3 free audits per day)
npx @vertaaux/cli audit https://example.com

# Sign in for full access
vertaa login
vertaa audit https://example.com --wait

# Check CLI health
vertaa doctor

Authentication

The audit command works without authentication for public URLs — you get 3 free audits per day in demo mode (IP-based quota). Sign in for full access, or upgrade to Pro for unlimited audits.

For all other commands (AI analysis, fix generation, etc.) and local URL audits, authentication is required. The CLI uses @vertaaux/sdk (^2.1.0) for API calls. The SDK handles auth automatically — you only need to configure credentials once. The bundled SDK supports AbortSignal cancellation, per-request timeoutMs overrides, and ES2022 Error.cause chains; the default request timeout is 120s (bumped from 30s in SDK 2.1.0). Three auth methods are supported:

1. Default credentials (recommended)

Run vertaa login to store credentials in ~/.vertaaux/credentials.json. The SDK reads these on every subsequent command — no flags needed.

vertaa login

This stores credentials for SDK-based auth. Use vertaa whoami to verify.

2. Environment variable

Set VERTAAUX_API_KEY (or VERTAAUX_TOKEN) in your shell or CI environment. The SDK reads this automatically on every command.

export VERTAAUX_API_KEY=vtx_...
vertaa audit https://example.com --wait

3. --api-key flag (override for scripts and CI)

Pass --api-key <key> to any command to override SDK auth for that invocation. This is intended for CI pipelines where the key comes from a secret manager or is passed inline.

VERTAAUX_API_KEY=${{ secrets.VERTAAUX_API_KEY }} vertaa audit https://example.com

Auth priority: --api-key flag > VERTAAUX_API_KEY env > VERTAAUX_TOKEN env > stored credentials.

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). The audit command works without auth in demo mode (3/day). AI commands 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 | | welcome | Re-run the first-run welcome screen | | telemetry enable\|disable\|status | Manage opt-in CLI telemetry |

Accessibility

| Command | Description | |---------|-------------| | a11y <url> | Multi-engine accessibility audit (axe-core + AccessLint + custom analyzers) |

The a11y command uses a dedicated API endpoint (/v1/a11y/audit) and returns WCAG-mapped findings with structured fix suggestions and fixability ratings.

| Option | Description | |--------|-------------| | --mode <basic\|standard\|deep> | Audit depth (default: basic) | | --min-impact <minor\|moderate\|serious\|critical> | Minimum impact level to report | | --fail-on-score <0-100> | Exit 1 if accessibility score below this value | | --fail-on-findings <n> | Exit 1 if critical+serious findings exceed n | | --format <json\|md> | Output format (default: json) | | --timeout <ms> | Wait timeout (default: 60000) |

Aliases

| Command | Alias For | |---------|-----------| | 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 | | a11y | json, md | json | | 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.6.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 key (used by SDK; --api-key flag overrides this per-command) | | VERTAAUX_TOKEN | Alternative auth token (checked before VERTAAUX_API_KEY) | | 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) | | VERTAAUX_TELEMETRY | Override telemetry consent (true/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

AI Agent Skill

Teach your AI coding agent (Claude Code, Cursor, Codex, Copilot, Gemini CLI, etc.) how to use the VertaaUX CLI:

npx skills add VertaaUX/agent-skills

Covers all CLI commands, CI/CD setup, SDK integration, and 10 use-case playbooks. Published on skills.sh.

Related

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