AI Commands

# Interactive login (device code flow)
vertaa login

# CI/non-interactive login
vertaa login --token <api-key>

# Or set environment variable
export VERTAAUX_API_KEY=your-key-here

vertaa suggest <intent...>

# Basic intent
vertaa suggest "check accessibility"

# Multi-word intent
vertaa suggest "audit my site for CI"

# Complex workflow
vertaa suggest "compare two pages and get a report"

# Setup tasks
vertaa suggest "set up CI quality gate"

# JSON output for tooling
vertaa suggest "what failed in my audit" --format json

  $ vertaa audit https://example.com --mode deep
  Run a comprehensive UX and accessibility audit

  $ vertaa audit https://example.com --fail-on error
  Audit with CI quality gate

{
  "suggestions": [
    {
      "command": "vertaa audit https://example.com --mode deep",
      "explanation": "Run a comprehensive UX and accessibility audit",
      "source": "local",
      "confidence": 85
    }
  ]
}

# AI mode -- full audit summary
vertaa explain [options]

# Evidence mode -- single finding
vertaa explain <finding-id> [options]

# AI summary from piped audit
vertaa audit https://example.com --json | vertaa explain

# AI summary with verbose evidence
vertaa explain --job abc123 --verbose

# AI summary from file
vertaa explain --file audit.json

# Evidence for a specific finding (legacy mode)
vertaa explain color-contrast-001 --job abc123

# Evidence from file
vertaa explain axe-label --file results.json

# JSON output
vertaa audit https://example.com --json | vertaa explain --format json

Summary
  > 12 accessibility issues found, 3 critical
  > Color contrast failures on 5 elements
  > Missing alt text on hero images

Issues

  ERROR Missing alt text (img-alt)
  Hero image lacks descriptive alt text
  Fix: Add alt="Description of hero image" to <img>

  WARNING Low contrast (color-contrast)
  Body text has 3.2:1 ratio (needs 4.5:1)
  Fix: Change text color to #333 or darken background

vertaa triage [options]

# Triage from piped audit
vertaa audit https://example.com --json | vertaa triage

# Verbose output with full details
vertaa triage --job abc123 --verbose

# From file with JSON output
vertaa triage --file audit.json --format json

# Compact summary (default)
vertaa audit https://example.com --json | vertaa triage

P0 Critical (3)
  Missing alt text, Keyboard trap, Missing form labels

P1 Important (5)
  Low contrast, Missing landmarks, Heading order, ...

P2 Nice to Have (4)
  Redundant links, Missing skip link, ...

Quick Wins (< 5 min each)
  * Add alt text to hero image
  * Add aria-label to search form

P0 Critical (3)
  > Missing alt text (img-alt)
    Screen readers cannot convey image content
    Effort: trivial

vertaa fix-plan [options]

# Fix plan from piped audit
vertaa audit https://example.com --json | vertaa fix-plan

# From job ID
vertaa fix-plan --job abc123

# JSON output for tooling integration
vertaa fix-plan --file audit.json --format json

# Pipe to jq for filtering
vertaa audit https://example.com --json | vertaa fix-plan --json | jq '.data.items[] | select(.effort == "trivial")'

Remediation Plan (8 items)
Estimated total effort: 4-6 hours

1. [critical] Add alt text to images
   Effort: trivial  Type: code
   1) Find all <img> tags without alt attributes
   2) Add descriptive alt text based on image context
   3) Use alt="" for decorative images
   Hint: document.querySelectorAll('img:not([alt])')

2. [high] Fix color contrast ratios
   Effort: small  Type: code
   1) Identify elements with contrast below 4.5:1
   2) Adjust text color or background color
   Hint: Use #333 for body text on white backgrounds

# From piped diff
<diff-source> | vertaa patch-review [options]

# From file
vertaa patch-review --diff-file <path> [options]

# Review a GitHub PR diff
gh pr diff 123 | vertaa patch-review --job abc123

# Review a git diff
git diff HEAD~1 | vertaa patch-review --job abc123

# From diff file with findings file
vertaa patch-review --diff-file fix.patch --findings audit.json

# Dry run to check inputs
gh pr diff 123 | vertaa patch-review --job abc123 --dry-run

# JSON output for CI integration
gh pr diff 123 | vertaa patch-review --job abc123 --format json

Verdict: SAFE  (confidence: 92%)

Patch correctly adds alt attributes to 3 images and fixes heading hierarchy.

Concerns:
  info @ line 42: Added alt text is generic ("image") -- consider more descriptive text

Findings addressed (3):
  + img-alt
  + heading-order
  + landmark-main

Findings remaining (2):
  - color-contrast
  - link-name

- name: Review patch safety
  run: |
    gh pr diff ${{ github.event.pull_request.number }} \
      | vertaa patch-review --job $AUDIT_JOB_ID --format json \
      | jq -e '.data.verdict == "SAFE"'

vertaa release-notes [options]

# From piped diff
vertaa diff --job-a abc --job-b def --json | vertaa release-notes

# From two job IDs directly
vertaa release-notes --job-a abc --job-b def

# From file
vertaa release-notes --file diff.json

# Human-readable output
vertaa release-notes --file diff.json --format human

# Save markdown to file
vertaa release-notes --job-a abc --job-b def > release-notes.md

# Accessibility Improvements - Sprint 42

## Developer Notes

- Fixed 5 color contrast violations (WCAG 2.1 AA)
- Added landmark roles to main navigation
- Resolved keyboard trap in modal dialog

## User-Facing Notes

- Improved readability across the application
- Better screen reader navigation support
- Fixed modal dialog accessibility

# URL mode (runs audits)
vertaa compare <urlA> <urlB> [options]

# File mode (LLM analysis)
vertaa compare --before <file> --after <file> [options]

# URL comparison (runs two audits)
vertaa compare https://staging.example.com https://prod.example.com --wait

# File-based LLM comparison
vertaa compare --before baseline.json --after current.json

# Verbose with category breakdown
vertaa compare --before baseline.json --after current.json --verbose

# JSON output
vertaa compare --before baseline.json --after current.json --format json

# CI gate: fail if score drops below 80
vertaa compare https://a.com https://b.com --wait --fail-on-score 80

Accessibility Score Improved After Navigation Refactor

Overall delta: +12

Improvements (5)
  + Fixed color contrast on navigation links
  + Added skip-to-content link
  + Improved heading hierarchy

Regressions (1)
  - New modal missing focus trap

Unchanged: 8

vertaa doc [options]

# Generate playbook from piped audit
vertaa audit https://example.com --json | vertaa doc

# From job ID with team name
vertaa doc --job abc123 --team "Frontend Team"

# From file
vertaa doc --file audit.json --team "Design System"

# Save to file
vertaa doc --job abc123 --team "Mobile" > playbook.md

# JSON for programmatic use
vertaa doc --file audit.json --format json

# Frontend Team Playbook

## Color Contrast

### Pattern
Body text and interactive elements frequently fail WCAG AA contrast ratios.

### Root Cause
Design tokens use light grays (#999) for secondary text.

### Correct Implementation
Use minimum 4.5:1 ratio for normal text, 3:1 for large text.

### Checklist
- [ ] Verify all text colors meet AA contrast ratios
- [ ] Test with browser contrast checker
- [ ] Update design tokens for secondary text