CLICommands
audit
Run UX and accessibility audits from the command line
vertaa audit
Run UX and accessibility audits on websites, local servers, or Storybook instances.
Synopsis
vertaa audit [options]Description
The audit command is the primary way to run UX audits. It analyzes a URL for usability, accessibility, information architecture, and performance issues, returning a score and detailed findings.
Quick Examples
Basic audit
$vertaa audit -u https://example.com
Deep audit with JSON output
$vertaa audit -u https://example.com --mode deep --format json -o results.json
CI mode with quality gates
$vertaa audit -u https://example.com --fail-on error --threshold 80
Options
Input Options
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
| -u, --url | string | required | URL to audit. Can be a public URL, localhost, or file:// URL |
| --repo | string | optional | GitHub repository to audit (format: owner/repo) |
| --storybook | string | optional | Storybook URL to audit component stories |
| --routes | string | optional | Comma-separated list of routes to audit (e.g., /,/about,/contact) |
Audit Mode
Mode
| Parameter | Type | Required | Description |
|---|---|---|---|
| --mode | string | optional | Audit depth: basic (fast, core checks), standard (balanced), deep (thorough, slower)Default: basic |
| --budget | string | optional | Time budget: quick (30s), standard (60s), full (120s+)Default: standard |
Mode Comparison:
| Mode | Checks | Time | Best For |
|---|---|---|---|
basic | ~50 rules | ~10s | Quick feedback, local dev |
standard | ~150 rules | ~30s | Balanced analysis, CI |
deep | ~300 rules | ~60s+ | Full audit, releases |
Output Options
Output
| Parameter | Type | Required | Description |
|---|---|---|---|
| --format | string | optional | Output format: human, json, sarif, junit, html, autoDefault: human |
| -o, --output | string | optional | Write results to file instead of stdout |
| --group-by | string | optional | Group results by: severity, category, routeDefault: severity |
Format Details:
| Format | Use Case | Notes |
|---|---|---|
human | Terminal display | Colored output, default |
json | Programmatic processing | Full data structure |
sarif | IDE/GitHub code scanning | SARIF 2.1.0 compliant |
junit | Test framework integration | JUnit XML format |
html | Shareable reports | Self-contained HTML |
auto | Context-aware | Uses human for TTY, json otherwise |
Filtering Options
Filtering
| Parameter | Type | Required | Description |
|---|---|---|---|
| --severity | string | optional | Filter by severity levels (comma-separated): error, warning, info |
| --category | string | optional | Filter by categories: ux, accessibility, ia, performance |
Quality Gate Options
Quality Gates
| Parameter | Type | Required | Description |
|---|---|---|---|
| --fail-on | string | optional | Exit with code 1 when issues of this severity found: error, warning, info, noneDefault: none |
| --threshold | number | optional | Exit with code 3 if overall score below this value (0-100) |
| --max-new-errors | number | optional | Exit with code 1 if more than N new errors (requires --baseline) |
| --max-new-warnings | number | optional | Exit with code 1 if more than N new warnings (requires --baseline) |
Baseline Options
Baseline
| Parameter | Type | Required | Description |
|---|---|---|---|
| --baseline | string | optional | Path to baseline file for comparison |
| --incremental | boolean | optional | Only audit routes changed in the PR (requires CI context)Default: false |
Execution Options
Execution
| Parameter | Type | Required | Description |
|---|---|---|---|
| --wait | boolean | optional | Wait for audit to complete before returningDefault: true |
| --no-wait | boolean | optional | Return immediately after queueing (get results later via status command) |
| --concurrency | number | optional | Maximum concurrent page auditsDefault: 3 |
| --timeout | number | optional | Timeout per page in millisecondsDefault: 60000 |
Debug Options
Debug
| Parameter | Type | Required | Description |
|---|---|---|---|
| --save-trace | boolean | optional | Save Playwright trace to .vertaaux/traces/ |
| --save-har | boolean | optional | Save HAR network log to .vertaaux/har/ |
| --screenshots | boolean | optional | Save page screenshots to .vertaaux/screenshots/ |
| --dom-snapshots | boolean | optional | Save DOM snapshots for debugging |
| --upload-artifacts | boolean | optional | Upload all artifacts to cloud storage |
CI/CD Options
CI/CD
| Parameter | Type | Required | Description |
|---|---|---|---|
| --json-logs | boolean | optional | Output structured JSON logs for CI parsing |
| --policy | string | optional | Path to policy file (vertaa.policy.yml) |
Monorepo Options
Monorepo
| Parameter | Type | Required | Description |
|---|---|---|---|
| --workspace | string | optional | Target specific workspace in a monorepo |
| --all-workspaces | boolean | optional | Audit all workspaces in the monorepo |
Exit Codes
| Code | Meaning |
|---|---|
0 | Success - audit completed, no quality gate failures |
1 | Issues found matching --fail-on severity or --max-new-* exceeded |
2 | Error - audit failed to complete (network error, invalid URL, etc.) |
3 | Score below --threshold value |
Examples
Basic Usage
Audit a public website:
$vertaa audit -u https://example.com
Audit localhost during development:
$vertaa audit -u http://localhost:3000
CI/CD Integration
Fail the build if any errors are found:
$vertaa audit -u $PREVIEW_URL --fail-on error
Fail if score drops below 80:
$vertaa audit -u $PREVIEW_URL --fail-on error --threshold 80
Output JSON for CI parsing:
$vertaa audit -u $PREVIEW_URL --format json --json-logs
Baseline Comparison
Compare against a baseline and fail on new issues:
$vertaa audit -u https://example.com --baseline baseline.json --max-new-errors 0
Deep Analysis
Run a thorough audit with all debug artifacts:
Deep audit with traces and screenshots
$vertaa audit -u https://example.com --mode deep --save-trace --screenshots
Multiple Routes
Audit specific routes:
$vertaa audit -u https://example.com --routes /,/about,/pricing,/contact
Storybook Audit
Audit Storybook components:
$vertaa audit --storybook http://localhost:6006
Filtered Output
Only show accessibility errors:
$vertaa audit -u https://example.com --category accessibility --severity error
SARIF Output
Generate SARIF for GitHub code scanning:
$vertaa audit -u https://example.com --format sarif -o results.sarif
Sample Output
VertaaUX CLI v1.0.0
Auditing: https://example.com
Mode: standard
[====================================] 100%
Audit Complete
──────────────────────────────────────────────
Overall Score: 85/100
Scores by Category:
UX: 88/100
Accessibility: 82/100
Information Arch: 87/100
Performance: 83/100
Issues Found: 12
Errors: 2
Warnings: 7
Info: 3
Top Issues:
[ERROR] Missing alt text on hero image
at img.hero-image
Fix: Add descriptive alt attribute
[ERROR] Color contrast ratio 3.2:1 below 4.5:1 minimum
at .button-secondary
Fix: Increase contrast to at least 4.5:1
[WARN] No skip link for keyboard navigation
at body
Fix: Add skip link as first focusable element
[WARN] Touch target 32x32px below 44x44px minimum
at .nav-link
Fix: Increase touch target to 44x44px
Full results: https://vertaaux.ai/reports/abc123Related
Also available
- POST /v1/audit - Create audit via API
- audits.create() - Create audit via SDK
baseline
Create baselines for comparison
diff
Compare two audit results
policy
Configure policy-as-code
CI/CD Integration
Set up automated audits
Was this page helpful?