All Commands

Full reference for every VertaaUX CLI command including audit, baseline, diff, and policy with usage examples

Complete reference for all commands available in the VertaaUX CLI.

Command Overview

Command	Description	Category
audit	Run UX and accessibility audits	Core
baseline	Create audit baselines	Core
diff	Compare audit results	Core
policy	Manage policy-as-code	Core
login	Authenticate with VertaaUX	Auth
logout	Clear stored credentials	Auth
whoami	Show authentication status	Auth
init	Initialize project configuration	Setup
doctor	Diagnose CLI health	Utility
status	Get audit job status	Utility
comment	Generate PR comment markdown	CI/CD
upload	Upload audit results to cloud	Storage
download	Download audit results from cloud	Storage
explain	AI-powered audit summary or finding evidence	Analysis
fix	Generate fix patch for issue	Remediation
fix-all	Generate patches for all issues	Remediation
verify	Verify patch fixes issue	Remediation
suggest	Convert intent to CLI command	AI
triage	P0/P1/P2 priority buckets	AI
fix-plan	Structured remediation plan	AI
patch-review	Diff safety review	AI
release-notes	Generate release notes	AI
doc	Team Playbook from findings	AI
a11y	Accessibility-focused audit	Alias
scan	UX scan (alias for audit)	Alias
compare	Compare two URL audits or LLM analysis	Alias

Option	Description
`--mode`	Audit depth: basic, standard, deep
`--format`	Output: human, json, sarif, junit, html (per-command)
`-o, --output`	Write results to file
`--fail-on`	Exit 1 on severity: error, warning, info
`--threshold`	Exit 3 if score below value
`--baseline`	Compare against baseline file
`--wait` / `--no-wait`	Wait for audit completion (default: wait)

Option	Description
`--path <path>`	Baseline file path (default: `.vertaaux/baseline.json`)
`--from-file <file>`	Create baseline from JSON audit file
`--ignore <id>`	Add single issue to existing baseline
`--reason <text>`	Reason for baseline/ignore
`--list`	Show baselined issues count and last update

Option	Description
`--baseline <path>`	Baseline file path (default: `.vertaaux/baseline.json`)
`--compare <job-id>`	Compare two audit jobs directly instead of baseline
`--from-file <file>`	Read current audit from JSON file instead of API
`--format`	Output: human, json (per-command)
`--verbose`	Show all present issues (not just new/fixed)

Subcommand	Description
`init`	Create starter policy file
`validate`	Check policy syntax
`show`	Display effective policy
`schema`	Output JSON schema

Authentication Commands

Authenticate with your VertaaUX account.

$vertaa login

Authenticates via device code flow (interactive) or direct token (CI).

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

Options:

Option	Description
`--token <token>`	Use API token directly (for CI/non-interactive use)
`--sso`	Use SSO login (not yet implemented)
`-b, --base <url>`	API base URL

logout

Clear stored credentials.

$vertaa logout

Removes credentials from ~/.vertaaux/credentials.json.

whoami

Show current authentication status.

$vertaa whoami

Authenticated as: user@example.com
Plan: Pro
Credits remaining: 950/1000

Setup Commands

init

Initialize VertaaUX configuration in your project.

$vertaa init

Creates .vertaaux.yml with sensible defaults. Runs an interactive wizard unless --yes is provided.

Options:

Option	Description
`-y, --yes`	Skip prompts, use defaults
`--ci <provider>`	CI provider: github, gitlab, circleci, azure, jenkins, none
`--fail-on <severity>`	Fail CI on severity: error, warning, info
`--threshold <score>`	Minimum score threshold (0-100)
`-f, --force`	Overwrite existing configuration

Utility Commands

doctor

Diagnose CLI health: configuration, authentication, and network connectivity.

$vertaa doctor

Checks performed:

Configuration file validity
Authentication status (stored credentials or environment tokens)
API connectivity

Options:

Option	Description
`--online`	Verify auth credentials against API (default: offline check)
`--deep`	Also run output contract self-tests
`--format`	Output: human, json

status

Get the status of an audit job.

$vertaa status job_abc123

Options:

Option	Description
`--fail-on-score <n>`	Exit 1 if score below n (0-100)

comment

Generate PR comment markdown from audit results.

$vertaa comment --input results.json

Options:

Option	Description
`--input <file>`	Audit results file
`--format`	Output: json, markdown (per-command)
`--baseline <path>`	Baseline file for comparison
`--post`	Post comment to PR (requires token)
`--pr <number>`	PR number for posting

CI Integration

Use vertaa comment in CI to automatically add audit summaries to pull requests.

Storage Commands

upload

Upload local audit results to VertaaUX cloud. If no job-id is given, uses the most recent artifact in .vertaaux/artifacts/.

$vertaa upload [job-id]

Options:

Option	Description
`--baseline`	Also upload baseline file
`--project <name>`	Cloud project name (default: current directory name)
`-b, --base <url>`	API base URL

download

Download audit results from VertaaUX cloud.

$vertaa download <job-id>

Options:

Option	Description
`--baseline`	Also download baseline file
`-o, --output <path>`	Output directory (default: `.vertaaux`)
`-b, --base <url>`	API base URL
`-f, --force`	Overwrite existing files without prompting

Analysis Commands

explain

Explain audit findings with AI, or show evidence for a specific finding.

Two modes:

AI mode (no finding-id): Accepts full audit JSON via stdin, --file, or --job. Produces a 3-bullet summary and per-issue explanations. Use --verbose for full evidence per issue.
Evidence mode (with finding-id): Shows the full evidence bundle for a specific finding (backward compatible).

$vertaa audit https://example.com --json | vertaa explain

$vertaa explain color-contrast-001 --job abc123

Options:

Option	Description
`--format`	Output: human, json (per-command)
`--job <id>`	Job ID (for fetching audit data or finding)
`--file <path>`	Load audit JSON from file
`--verbose`	Show full evidence per issue (AI mode)

Remediation Commands

fix

Generate a fix patch for a specific issue.

$vertaa fix <job-id> --issue <id> --file-content <code>

Options:

Option	Description
`--issue <id>`	Issue ID to fix (required)
`--file-content <code>`	Source code content (required)

fix-all

Generate fix patches for all issues in an audit.

$vertaa fix-all <job-id> --file-content <code>

Options:

Option	Description
`--file-content <code>`	Source code content (required)
`--auto-fix-only`	Only process auto-fixable issues

Review Before Applying

Always review generated patches before applying. AI-generated fixes may need manual adjustment.

verify

Verify that a patch successfully fixes an issue.

$vertaa verify --search <text> --replace <text> --issue <id> --url <url> --selector <css>

Runs a targeted audit to confirm the issue is resolved.

Options:

Option	Description
`--search <text>`	Search pattern (required)
`--replace <text>`	Replace pattern (required)
`--issue <id>`	Issue ID (required)
`--url <url>`	Target URL (required)
`--selector <css>`	CSS selector (required)
`--timeout <ms>`	Timeout in milliseconds

AI commands use server-side LLM processing to provide intelligent analysis of audit results. All AI commands require authentication (vertaa login or VERTAAUX_API_KEY). They accept input via stdin pipe, --file, or --job.

Full AI commands reference

suggest

Convert natural language intent into exact CLI commands.

$vertaa suggest "check contrast on my site"

Uses a local command catalog first, falling back to the API for complex intents. No audit data required.

Options:

Option	Description
`--format`	Output: human, json

triage

Prioritize audit findings into P0/P1/P2 buckets with effort estimates and quick-wins.

$vertaa audit https://example.com --json | vertaa triage

Options:

Option	Description
`--job <id>`	Fetch audit data from a job ID
`--file <path>`	Load audit JSON from file
`--format`	Output: human, json
`--verbose`	Expand each priority bucket with full details

fix-plan

Generate a structured remediation plan with ordered steps, effort estimates, and code hints.

$vertaa audit https://example.com --json | vertaa fix-plan

Options:

Option	Description
`--job <id>`	Fetch audit data from a job ID
`--file <path>`	Load audit JSON from file
`--format`	Output: human, json

patch-review

Review a patch/diff against audit findings for safety. Returns a SAFE, UNSAFE, or NEEDS_REVIEW verdict.

$gh pr diff 123 | vertaa patch-review --job abc123

Options:

Option	Description
`--job <id>`	Fetch findings from a job ID
`--findings <path>`	Load findings JSON from file
`--diff-file <path>`	Load diff from file instead of stdin
`--format`	Output: human, json

release-notes

Generate developer and PM release notes from audit diff data.

$vertaa diff --job-a abc --job-b def --json | vertaa release-notes

Options:

Option	Description
`--file <path>`	Load diff JSON from file
`--job-a <id>`	First audit job ID (baseline)
`--job-b <id>`	Second audit job ID (current)
`--format`	Output: human, json, markdown

doc

Generate a Team Playbook document from recurring audit findings -- patterns, root causes, correct implementations, and checklists.

$vertaa audit https://example.com --json | vertaa doc --team Frontend

Options:

Option	Description
`--job <id>`	Fetch audit data from a job ID
`--file <path>`	Load audit JSON from file
`--team <name>`	Team name for the playbook header
`--format`	Output: json, markdown

Alias Commands

These commands are aliases for common operations:

Accessibility-focused audit. Alias for audit --category accessibility.

$vertaa a11y https://example.com

scan

General UX scan. Alias for audit.

$vertaa scan https://example.com

compare

Compare two audits -- by URL (runs audits and shows score deltas) or by file (LLM-powered narrative analysis).

$vertaa compare https://v1.example.com https://v2.example.com --wait

$vertaa compare --before baseline.json --after current.json

Options:

Option	Description
`--before <path>`	Baseline audit JSON file (LLM mode)
`--after <path>`	Current audit JSON file (LLM mode)
`--wait`	Wait for audits to complete (URL mode)
`--verbose`	Show category score deltas and full narrative
`--format`	Output: human, json

Global Options

These options work with any command:

Option	Description
`-h, --help`	Show help for command
`-v, --version`	Show CLI version
`-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 (JSON stdout, diagnostics stderr)
`--color / --no-color`	Force or disable colored output
`--dashboard / --no-dashboard`	Force or disable live dashboard
`--dry-run`	Show what would happen without executing
`-y, --yes`	Auto-confirm all interactive prompts
`--verbose`	Expand output with additional details

Environment Variables

Variable	Description
`VERTAAUX_API_KEY`	API authentication key
`VERTAAUX_TOKEN`	Alternative auth token (used by CI token detection)
`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

Exit Codes

Code	Meaning
`0`	Success
`1`	Issues found / Quality gate failed
`2`	Command error (invalid input, network error)
`3`	Score below threshold
`130`	Interrupted (Ctrl+C)

All Commands

Quickstart

Configuration

CI/CD Integration

On this page