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

The CLI uses cosmiconfig for auto-detection. Search places (first match wins):

--config flag (explicit path, highest priority)
.vertaaux.yml
.vertaaux.yaml
.vertaaux.json
vertaaux.config.js
vertaaux.config.mjs
vertaaux.config.cjs
package.json (vertaaux key)

Configuration Precedence

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

Built-in defaults - Sensible starting point
Configuration file - Team-shared settings
Environment variables - Deployment-specific overrides
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: VERTAAUX_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

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

Field Reference

Authentication

Parameter	Type	Required	Description
apiKey	`string`	optional	VertaaUX API key. Prefer using VERTAAUX_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

Parameter	Type	Required	Description
defaultUrl	`string`	optional	Default URL for audits. Used when no URL argument is provided.
mode	`string`	optional	Default audit mode: basic (fast), standard (balanced), deep (thorough).Default: `basic`
threshold	`number`	optional	Minimum acceptable score. CLI exits with code 3 if score is below this value.Default: `0`
failOn	`string`	optional	Fail (exit 1) when issues of this severity found: error, warning, info, none.Default: `none`

Output

Output Configuration

Parameter	Type	Required	Description
output.format	`string`	optional	Output format. 'auto' uses human for TTY, json otherwise.Default: `auto`
output.groupBy	`string`	optional	How to group results: severity, category, or route.Default: `severity`

Baseline

Baseline Configuration

Parameter	Type	Required	Description
baseline.path	`string`	optional	Path to baseline file for comparison.Default: `.vertaaux/baseline.json`
baseline.autoUpdate	`boolean`	optional	Automatically update baseline after successful audits.Default: `false`

CI/CD

CI/CD Configuration

Parameter	Type	Required	Description
ci.template	`string`	optional	CI provider for optimized behavior: github, gitlab, circleci, azure, jenkins.Default: `none`

Performance

Performance Settings

Parameter	Type	Required	Description
timeout	`number`	optional	Per-page timeout in milliseconds.Default: `60000`
interval	`number`	optional	Polling interval for async operations.Default: `5000`

Environment Variables

The CLI reads these environment variables:

Variable	Description
`VERTAAUX_API_KEY`	API authentication key (overrides config `apiKey`)
`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`, auto-enabled in CI)
`NO_COLOR`	Disable colored output
`FORCE_COLOR`	Force colored output

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
baseline:
  path: .vertaaux/baseline.json

Strict Production

# .vertaaux.yml
mode: deep
threshold: 90
failOn: warning
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 VERTAAUX_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

The CLI validates your configuration automatically when loading it. If the config file has invalid values, you will see a clear error message with the specific issue.

Configuration is validated against a JSON Schema using Ajv, checking:

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

Use the doctor command to check your configuration and other CLI health:

$vertaa doctor

This checks config file loading, authentication status, and network connectivity.