VertaaUX CLI

Run UX and accessibility audits from the terminal or CI pipelines.

Install

``bash
npm install -g @vertaaux/cli
`

Or run with npx:

`bash
npx @vertaaux/cli --help
`

Quick Start

`bash


1. Authenticate

vertaa login

2. Run an audit

vertaa audit https://example.com --wait

3. Check CLI health

vertaa doctor
`

Authentication

The CLI checks for credentials in this order:

1. Environment variables (checked in order):
- VERTAAUX_TOKEN
- VERTAAUX_API_KEY

2. Stored credentials from interactive login:
`bash
vertaa login
`
Credentials are stored in ~/.vertaaux/credentials.json.

3. Direct token for CI/non-interactive use:
`bash
vertaa login --token
`

Verify authentication:

`bash
vertaa whoami
`

Commands

$3

| Command | Description |
|---------|-------------|
| audit | 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 |

$3

| Command | Description |
|---------|-------------|
| explain | Show evidence bundle for a finding |
| comment | Generate PR comment from audit results |
| fix | Generate a fix patch for an issue |
| fix-all | Generate fix patches for all issues |
| verify | Verify that a patch fixes an issue |

$3

| 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 | Check audit job status |
| upload | Upload audit results to cloud storage |
| download | Download audit results from cloud storage |

$3

| Command | Alias For |
|---------|-----------|
| a11y | Accessibility-focused audit (filters for a11y issues) |
| scan | UX scan (alias for audit) |
| compare | Compare audits of two URLs |

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 |
| comment | json, markdown | markdown |
| explain | human, json | human |
| policy show | json, yaml | yaml |
| diff | human, json | human |

Usage:

`bash
vertaa audit https://example.com --format json
vertaa audit https://example.com --format sarif > results.sarif
vertaa comment --input results.json --format markdown
`

$3

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:

`json
{
"meta": {
"version": "0.1.0",
"timestamp": "2026-02-08T12:00:00.000Z",
"command": "audit",
"args": ["https://example.com", "--format", "json"]
},
"data": {
"scores": { "overall": 85 },
"issues": []
}
}
`

$3

All diagnostic output goes to stderr, keeping stdout clean for piping:

`bash
vertaa audit https://example.com --format json | jq '.data.scores'
vertaa audit https://example.com --format json > results.json
`

Global Options

These options work with any command:

| Option | Description |
|--------|-------------|
| -b, --base | API base URL override |
| -c, --config | 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 |
| -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.

$3

1. .vertaaux.yml
2. .vertaaux.yaml
3. .vertaaux.json
4. vertaaux.config.js
5. vertaaux.config.mjs
6. vertaaux.config.cjs
7. package.json (vertaaux key)

Or specify explicitly:

`bash
vertaa audit https://example.com --config path/to/.vertaaux.yml
`

$3

`
flag > env var > config file > default
`

$3

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) |

$3

`yaml


.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:

`bash
vertaa init
vertaa init --ci github --yes
`

Security

$3

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

$3

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

$3

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 authentication key |
| VERTAAUX_TOKEN | Alternative auth token (checked first) |
| VERTAAUX_API_BASE | API base URL override |
| NO_COLOR | Disable colored output |
| FORCE_COLOR | Force colored output |

CI/CD Integration

$3

`yaml
- 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
`

$3

`bash


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 --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
``

Related

- Migration Guide -- Breaking changes in this release
- Configuration Docs -- Full config reference
- CI/CD Integration -- Pipeline setup guides