@vertaaux/cli

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

• .vertaaux.yml
• .vertaaux.yaml
• .vertaaux.json
• vertaaux.config.js
• vertaaux.config.mjs
• vertaaux.config.cjs
• 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