Skip to main content

Quick Start

This guide gets you from zero to a passing vyb check in under 5 minutes. You will initialize a spec, pick a pre-built pack, and run your first check.

Step 1 — Initialize your spec​

In the root of your project:

vyb init

This creates .vyb/spec.yaml with a minimal starter configuration:

.vyb/spec.yaml
spec:
  version: 1
  project: my-project
  description: vybdocs constraint spec

settings:
  severity-floor: info
  allow-severity-downgrade: false

categories: {}

Step 2 — Pick a pack (optional but recommended)​

If your project falls into a vertical, start from a pre-built pack:

# EU fintech / MiFID II
vyb init --pack eu-fintech

# US healthtech with PHI handling
vyb init --pack us-healthtech-phi

# US fintech / PCI-DSS
vyb init --pack us-fintech

# General EU SaaS
vyb init --pack eu-saas-general

# General US SaaS
vyb init --pack us-saas-general

The pack is merged into your .vyb/spec.yaml. You can then add custom rules on top.

Step 3 — Run your first check​

vyb check

On a clean repo with no violations, you see:

vyb check  v1.0.0
───────────────────────────────────────────
  Project:  my-project
  Spec:     .vyb/spec.yaml
  Diff:     HEAD (12 files, 847 lines)

  Rules evaluated: 24
  Violations:      0
  Evidence Pack:   .vyb/evidence/2026-05-18T14-03-22Z.pdf

  PASS
───────────────────────────────────────────

Step 4 — Inspect violations​

If vyb check finds violations, the output lists each one:

vyb check  v1.0.0
───────────────────────────────────────────
  Project:  my-project
  Spec:     .vyb/spec.yaml
  Diff:     HEAD (3 files, 142 lines)

  Rules evaluated: 24
  Violations:      2

  [BLOCK]  sec-001 / no-eval
           src/utils/parser.ts:47
           Pattern matched: eval(
           Remediation: Replace eval() with JSON.parse() or a
           safe expression evaluator.

  [WARN]   fe-003 / no-direct-dom
           src/components/Widget.tsx:12
           Pattern matched: document.getElementById
           Remediation: Use React refs (useRef) instead of
           direct DOM access.

  FAIL  (1 block, 1 warn)
───────────────────────────────────────────
Exit code: 1

Exit code 1 means one or more block-severity rules were violated. warn violations are reported but do not cause a non-zero exit by default (configurable).

Step 5 — Check a specific file or diff​

# Check only staged changes
vyb check --staged

# Check against a specific base commit
vyb check --base main

# Check specific files
vyb check --files src/utils/parser.ts

# Dry run — report violations without failing
vyb check --dry-run

Step 6 — Open the web UI​

For an interactive view of your spec and live rule traces:

vyb ui

This starts a local server at http://localhost:7777. The UI shows your full spec, a live rule matrix, recent check results, and a chat panel for querying rules.

What happens next​

Next: Your First Check in Detail