audit

Run UX and accessibility audits on websites, local servers, or Storybook from the CLI with configurable thresholds

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 v0.3.3

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/abc123

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?

audit

baseline

diff

policy

CI/CD Integration

On this page