Quickstart — up and running in 10 minutes

This guide walks through installing the Fpgawright CLI, connecting it to your RTL repository, running your first analysis, and setting up a CI hook.

Step 1 — Install the CLI

The CLI requires Node.js 18+ or you can download a standalone binary. The binary has no runtime dependencies.

# Install via npm
npm install -g @fpgawright/cli

# Or download the Linux binary
curl -fsSL https://fpgawright.com/install.sh | sh

Verify the installation:

fpgawright --version
# fpgawright v0.9.2

Step 2 — Connect your repository

Authenticate with your API key. You can find your key in the dashboard after access is granted.

fpgawright auth login --key $FPGAWRIGHT_API_KEY

Create a config file in your repo root. This tells Fpgawright where to find your RTL source:

# .fpgawright.yaml
rtl:
  paths:
    - ./rtl
    - ./src/rtl
  language: systemverilog
output:
  format: json
  fail_on: error

Step 3 — Run your first analysis

From your repo root, run:

fpgawright analyze

The analysis runs in two passes. You'll see progress output in your terminal. A typical 100k-line design completes in 2–4 minutes.

→ Indexing RTL source (247 files)
→ Running base rule engine (140 rules)
→ Applying learned patterns
→ Generating report

Analysis complete: 3 errors, 7 warnings
  GLT-003  ERROR  clock_sync_module.sv:142  CDC violation
  RST-007  ERROR  top_module.sv:89  Async reset in sync domain
  FSM-012  WARN   state_machine.sv:203  Unreachable state S_IDLE
  (+ 6 more warnings)

Full report: ./fpgawright-report.json

Step 4 — Read your first report

The JSON report contains the full ranked violation list. Open it directly or use the CLI to render a human-readable summary:

fpgawright report show
fpgawright report export --format pdf --output ./rtl-verification.pdf

Each violation entry includes:

  • Rule ID (e.g., GLT-003) and description
  • File path and line number
  • Module name and signal context
  • Severity and learned weight score
  • Link to the relevant spec clause

Step 5 — Set up your CI hook

Add the Fpgawright GitHub Actions workflow to your repository:

# .github/workflows/fpgawright.yml
name: RTL Verification
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Fpgawright RTL verification
        uses: fpgawright/action@v2
        with:
          api-key: ${{ secrets.FPGAWRIGHT_API_KEY }}
          rtl-path: ./rtl
          diff-only: true

The diff-only: true flag runs in diff-aware mode — the action reports only violations introduced by the current commit, not the full baseline list. This mode is recommended for PR-gating workflows to avoid noise from pre-existing findings.

Configuration reference

The .fpgawright.yaml file supports the following top-level keys:

  • rtl.paths — list of directories containing RTL source files
  • rtl.language — verilog, systemverilog, vhdl, or mixed
  • rules — per-rule severity overrides and enable/disable toggles
  • learning.enabled — enable historical bug pattern weighting (default: true)
  • learning.weight_factor — multiplier for learned pattern weights (default: 2.0)
  • output.format — json or pdf
  • output.fail_on — exit non-zero on error, warn, or none
Next step: explore the RTL Rules Reference to understand which rules are enabled by default and how to configure them for your architecture.