Skip to main content
VertaaUX Docs
CLI

Configuration

Configure VertaaUX CLI defaults with .vertaaux.yml

Configuration

Configure CLI defaults using a .vertaaux.yml configuration file. This eliminates repetitive command-line flags and ensures consistent settings across your team.

Configuration File

The CLI looks for .vertaaux.yml in the current directory and parent directories. The first file found is used.

Create a starter configuration file
$vertaa init

File Locations

Search order (first match wins):

  1. --config flag (explicit path)
  2. ./.vertaaux.yml (current directory)
  3. ./.vertaaux/config.yml (hidden directory)
  4. ~/.vertaaux.yml (home directory)
  5. ~/.vertaaux/config.yml (home config directory)

Configuration Precedence

Settings are applied in this order (later overrides earlier):

  1. Built-in defaults - Sensible starting point
  2. Configuration file - Team-shared settings
  3. Environment variables - Deployment-specific overrides
  4. Command-line flags - One-off overrides

Complete Schema

# .vertaaux.yml

# JSON Schema for editor autocompletion (optional)
$schema: https://vertaaux.ai/schemas/config.json

# Authentication
# Prefer environment variable: VERTAA_API_KEY
apiKey: vx_live_...

# Default URL for audits (optional)
defaultUrl: https://example.com

# Default audit mode: basic | standard | deep
mode: basic

# Minimum score threshold (0-100)
# Exit code 3 if score is below this
threshold: 0

# Fail on severity: error | warning | info | none
failOn: none

# Output configuration
output:
  # Format: auto | json | sarif | junit | html | human
  format: auto
  # Group results by: severity | category | route
  groupBy: severity

# Baseline configuration
baseline:
  # Path to baseline file
  path: .vertaaux/baseline.json
  # Automatically update baseline on successful audit
  autoUpdate: false

# CI/CD configuration
ci:
  # CI template: github | gitlab | circleci | azure | jenkins | none
  template: none
  # Post comments to PRs
  postComments: false
  # JSON logs for machine parsing
  jsonLogs: false

# Timing
timeout: 60000     # Per-page timeout in milliseconds
interval: 5000     # Polling interval in milliseconds

# Concurrent audits
concurrency: 3

Field Reference

Authentication

Authentication
ParameterTypeRequiredDescription
apiKeystringoptionalVertaaUX API key. Prefer using VERTAA_API_KEY environment variable instead for security.

Security Warning

Never commit API keys to version control. Use environment variables or your CI provider's secrets management.

Defaults

Default Settings
ParameterTypeRequiredDescription
defaultUrlstringoptionalDefault URL for audits. Used when -u flag is omitted.
modestringoptionalDefault audit mode: basic (fast), standard (balanced), deep (thorough).Default: basic
thresholdnumberoptionalMinimum acceptable score. CLI exits with code 3 if score is below this value.Default: 0
failOnstringoptionalFail (exit 1) when issues of this severity found: error, warning, info, none.Default: none

Output

Output Configuration
ParameterTypeRequiredDescription
output.formatstringoptionalOutput format. 'auto' uses human for TTY, json otherwise.Default: auto
output.groupBystringoptionalHow to group results: severity, category, or route.Default: severity

Baseline

Baseline Configuration
ParameterTypeRequiredDescription
baseline.pathstringoptionalPath to baseline file for comparison.Default: .vertaaux/baseline.json
baseline.autoUpdatebooleanoptionalAutomatically update baseline after successful audits.Default: false

CI/CD

CI/CD Configuration
ParameterTypeRequiredDescription
ci.templatestringoptionalCI provider for optimized behavior: github, gitlab, circleci, azure, jenkins.Default: none
ci.postCommentsbooleanoptionalPost audit results as PR comments.Default: false
ci.jsonLogsbooleanoptionalOutput structured JSON logs for CI parsing.Default: false

Performance

Performance Settings
ParameterTypeRequiredDescription
timeoutnumberoptionalPer-page timeout in milliseconds.Default: 60000
intervalnumberoptionalPolling interval for async operations.Default: 5000
concurrencynumberoptionalMaximum concurrent page audits.Default: 3

Environment Variables

Override any configuration with environment variables:

VariableConfig EquivalentDescription
VERTAA_API_KEYapiKeyAPI authentication key
VERTAA_DEFAULT_URLdefaultUrlDefault URL to audit
VERTAA_MODEmodeDefault audit mode
VERTAA_THRESHOLDthresholdMinimum score threshold
VERTAA_FAIL_ONfailOnFailure severity
VERTAA_FORMAToutput.formatOutput format
VERTAA_TIMEOUTtimeoutPage timeout
VERTAA_CONCURRENCYconcurrencyConcurrent audits

Example Configurations

Local Development

# .vertaaux.yml
defaultUrl: http://localhost:3000
mode: basic
output:
  format: human
  groupBy: severity

CI/CD Pipeline

# .vertaaux.yml
mode: standard
threshold: 80
failOn: error
output:
  format: json
  groupBy: category
ci:
  template: github
  jsonLogs: true
baseline:
  path: .vertaaux/baseline.json

Strict Production

# .vertaaux.yml
mode: deep
threshold: 90
failOn: warning
concurrency: 1
baseline:
  autoUpdate: false

Team Configuration

# .vertaaux.yml
# Committed to repo - shared by team
mode: standard
threshold: 75
failOn: error
output:
  groupBy: category
baseline:
  path: baselines/main.json
# API key NOT included - use VERTAA_API_KEY env var

Per-Project Configuration

Different projects can have different configurations:

monorepo/
├── .vertaaux.yml           # Root config (shared defaults)
├── apps/
│   ├── web/
│   │   └── .vertaaux.yml   # Web app config (overrides root)
│   └── admin/
│       └── .vertaaux.yml   # Admin app config (overrides root)
└── packages/

Run from the project directory to use its config:

cd apps/web && vertaa audit

Or specify config explicitly:

$vertaa audit --config apps/admin/.vertaaux.yml

Validation

Validate your configuration file:

$vertaa config validate

This checks:

  • YAML syntax
  • Schema compliance
  • Valid enum values
  • Type correctness

Editor Support

Add JSON Schema for autocompletion in your editor:

# .vertaaux.yml
$schema: https://vertaaux.ai/schemas/config.json

# Your configuration below...
mode: standard

VS Code: Automatically provides completions and validation.

JetBrains IDEs: Configure in Settings > Languages > JSON Schema Mappings.

Debugging Configuration

See effective configuration (all sources merged):

$vertaa config show
Effective configuration:
apiKey: vx_live_...****
mode: standard
threshold: 80
failOn: error
output:
format: json
groupBy: category

Sources:
- /Users/you/project/.vertaaux.yml
- Environment: VERTAA_API_KEY

Policy Configuration

Configure quality gates with vertaa.policy.yml

Installation

Authentication setup

CI/CD Integration

Use configuration in pipelines

Was this page helpful?

Installation

Install and configure the VertaaUX CLI on your system

audit

Run UX and accessibility audits from the command line

On this page

ConfigurationConfiguration FileFile LocationsConfiguration PrecedenceComplete SchemaField ReferenceAuthenticationDefaultsOutputBaselineCI/CDPerformanceEnvironment VariablesExample ConfigurationsLocal DevelopmentCI/CD PipelineStrict ProductionTeam ConfigurationPer-Project ConfigurationValidationEditor SupportDebugging ConfigurationRelated