Public docs

Verglos CLI reference for real delivery workflows.

Install, scan, wire CI, activate Pro, run MCP, and understand what the local report is telling you. Source stays on your machine; reports are written beside your code.

Start with install Compare plans GitHub repo

quick start

npx verglos

# reports written locally
verglos-report.html
verglos-report.json

Free: Unlimited local scans
Output: HTML + JSON
Runtime: Node.js 20+
Privacy: No source upload

Local scan

Start with evidence on your machine

Run one command, keep source local, and get HTML plus JSON reports with paths, line numbers, and fix guidance.

CI enforcement

Stop risky changes before merge

Free blocks criticals. Pro adds score thresholds so teams can keep a minimum security bar in every pipeline.

Agent guardrails

Give coding agents a security tool

MCP exposes scan, package checks, and finding explanations to Cursor, Claude Code, Windsurf, Cline, and similar tools.

Monitoring

Keep dependency risk visible

Pro monitoring registers your dependency tree and alerts when new OSV vulnerabilities land after the first scan.

Install

npx is the recommended way. Pins to the latest published version automatically. Requires Node.js 20+.

npx / global / project

Three ways to install Verglos.

npx verglos            # one-off, no install
npm i -g verglos       # global (avoids the network round-trip)
pnpm add -D verglos    # in a project

Scanning

Every command writes verglos-report.html + verglos-report.json next to your code.

verglos scan

Full security scan across all detectors.

verglos scan                  # standard scan
verglos scan --watch          # re-scan on file changes
verglos scan --quiet          # no terminal output; reports still written
verglos scan --all            # include low-confidence findings
verglos scan --strict         # include test-file findings in the score
verglos scan --no-provenance  # skip AI-authorship analysis (fastest)
verglos scan --verify-secrets # ping GitHub/Stripe to prove matched keys are live

Note · Provenance analysis is capped at 300 files by default for speed. Override with VERGLOS_PROVENANCE_FILE_CAP=<n> or opt out with --no-provenance.

verglos score

Prints the 0-100 score only. Useful for shell pipelines.

verglos score

verglos secrets

Secrets-only scan. Fastest of the focused commands.

verglos secrets

verglos deps

Dependency CVE audit only. Uses OSV.

verglos deps

Understanding your report

Two features shape what shows up in verglos-report.html — both were built to keep the scanner from crying wolf.

Context tags — why some findings look critical but show as info

Pattern-matching alone catches too much noise. A password in docs/setup.md isn't a leaked secret; it's a code sample. A Bearer token in openapi.yml isn't a credential; it's an API-spec example. Verglos runs a post-detection pass that downgrades findings whose file path tells you they can't be a production threat. Each downgrade is stamped with a `contextTag` so you know exactly why the severity dropped — nothing is silently hidden.

// A downgraded finding in verglos-report.json:
{
  "rule": "D4-001",
  "severity": "info",              // downgraded
  "originalSeverity": "critical",  // what the detector said
  "contextTag": "docs",            // why the downgrade fired
  "file": "docs/setup.md",
  ...
}

// The 8 tags currently applied:
//   docs               .md / .rst / docs/ / CONTRIBUTING / README
//   dev-fixture        .env.example / docker-compose*.yml / docker/
//   ci-workflow        .github/workflows/ / .depot/ / .buildkite/
//   test-fixture       test/ / __tests__/ / cypress/ / *.test.*
//   vendored-bundle    public/libraries/ / vendor/ / *.min.js
//   build-config       webpack.config.* / rspack.config.* / vite.config.*
//   generated          generated/ / __generated__/ / .generated.*
//   api-spec-example   openapi.yml / swagger.yml / api/v*/*.yml

Note · Bottom line: numbers you see for `critical` and `high` are ones a human security reviewer would care about. The rest is tagged, not hidden.

Vendored library CVEs (rule D6-002)

Every SAST scanner filters files under public/libraries/, vendor/, and *.min.js out of its analysis — because they aren't in the lockfile. Verglos does the opposite: it walks those paths, parses `name@version` from filenames like `echarts@5.4.3.js`, and cross-references OSV. If a CVE exists, it emits a critical finding with the attack narrative — because those files ARE served to every browser that loads your app, even though npm audit can't see them.

// A D6-002 finding in verglos-report.json:
{
  "rule": "D6-002",
  "detector": "vendored-cves",
  "severity": "high",
  "title": "Vendored library with known CVE: jsonwebtoken@8.5.1",
  "file": "public/libraries/jsonwebtoken@8.5.1.js",
  "package": "jsonwebtoken",
  "cve": "GHSA-8cf7-32gw-wr33",
  "why": "This library is checked into the repo (not managed by npm), so it never appears in your lockfile and `npm audit` won't see it. But the file IS served to every browser that loads your app. If the CVE is exploitable, every visitor is exposed. Rotate to a patched version or remove.",
  ...
}

Note · Filename patterns recognised: `name@version.js`, `name-version.js`, `name.version.js`, optionally .min or .bundle. Detector caps at 200 unique lookups per scan and uses OSV with a 5-second timeout per query.

CI and Auto-fix

verglos ci

Exit non-zero on criticals (Free) or on a score threshold (Pro). Use as a CI gate.

verglos ci                    # blocks on any critical (Free)
verglos ci --threshold 80     # blocks if score < 80 (Pro)
verglos ci --quiet            # suppress output

Note · Free tier gets threshold-less CI (still blocks on criticals). Threshold gating requires Pro.

verglos fixPro

Framework-aware auto-remediation. Starts with security headers; more rules land per release.

verglos fix

GitHub Actions example

Drop-in workflow snippet for pinning to Pro in CI.

- name: Activate Verglos Pro
  run: npx verglos activate "$VERGLOS_LICENSE_KEY" --ci
  env:
    VERGLOS_LICENSE_KEY: ${{ secrets.VERGLOS_LICENSE_KEY }}

- name: Verglos CI scan
  run: npx verglos ci --threshold 80

Note · activate --ci exits 2 on invalid/expired keys so the job fails fast instead of running unpaid.

Authentication

verglos whoami

Shows your current plan, license (masked), renewal date, and machine. Falls back to cached info with a (cached) marker when offline.

verglos whoami

# You:      you@example.com
# Plan:     PRO
# License:  vg_xxxx…yyyy
# Renewal:  Jan 15, 2027 (in 365 days)
# Machine:  a1b2c3d4… (this machine)

verglos activate <key>

Non-interactive activation for CI. Validates against the server before saving; garbage keys are rejected without persisting.

verglos activate vg_xxxx_yyyy_zzzz
verglos activate $VERGLOS_LICENSE_KEY --ci   # exits 2 on failure

Continuous Monitoring

verglos monitor registerPro

Registers your dep tree for hourly OSV checks. Alerts to email, Slack, or a generic webhook when new CVEs land.

verglos monitor register --email you@example.com
verglos monitor register --slack https://hooks.slack.com/services/...
verglos monitor register --webhook https://your.app/verglos-alerts
verglos monitor register --label prod-api   # override auto-detected label

Pre-commit Hook

verglos hook

Install the pre-commit git hook once.

verglos hook

verglos precommit

The scan that runs from the pre-commit hook. Fast secrets + criticals check under a strict time budget.

verglos precommit                     # 2s budget (default)
verglos precommit --timeout 5000      # 5s budget

AI Agent Integration (MCP)

Exposes Verglos as MCP tools so agents can scan a project, check a package name before writing an import, and explain a finding.

verglos mcp

Start the MCP stdio server. Agents call this.

verglos mcp                    # start the server (agents call this)
verglos mcp --print-config     # print the JSON to paste into your agent's config

Note · Compatible with Cursor, Claude Code, Windsurf, Cline. Use --print-config to get the exact snippet for each.

Utilities

verglos init

Configure Verglos in the current project. Writes .verglos.config.js.

verglos init         # interactive
verglos init -y      # non-interactive, keep existing config, skip hook install

verglos explain

Explain any Verglos rule — why it exists, how to fix it.

verglos explain              # list every rule
verglos explain D2-001       # explain one rule
verglos explain --list       # same as no-arg

verglos badge

Prints Markdown for a README badge showing your current score.

verglos badge

verglos update

Self-upgrade to the latest npm version.

verglos update

Configuration

Sane defaults. Customize when you need to.

.verglos.config.js

Project-level config. Drop in the repo root.

// .verglos.config.js
module.exports = {
  ignorePaths: ["**/fixtures/**", "**/legacy/**"],
  failOnCritical: true,
  failThreshold: 80,
  secretScanDepth: 100,
};

.verglosignore

Path-only ignores. Same syntax as .gitignore.

**/fixtures/**
legacy-*.js
!legacy-important.js

Environment Variables

Env override reference

All env vars Verglos honors.

VERGLOS_API_URL=https://verglos.com                # override server
VERGLOS_TELEMETRY=0                                # disable anonymous telemetry
VERGLOS_PROVENANCE_FILE_CAP=1000                   # raise provenance file cap
VERGLOS_LICENSE_KEY=vg_xxxx_yyyy_zzzz              # used by activate --ci

Plans

What each tier unlocks

Free is the complete local scanner and can be used unlimited times. Paid tiers add enforcement, monitoring, team proof, and readiness workflows around that scanner.

Capability	Free	Pro	Studio	Compliance
Unlimited local scans	Yes	Yes	Yes	Yes
Full paths, line numbers, findings	Yes	Yes	Yes	Yes
Local HTML/JSON report	Yes	Yes	Yes	Yes
AI-provenance layer	Yes	Yes	Yes	Yes
MCP server	Yes	Yes	Yes	Yes
CI blocks on criticals	Yes	Yes	Yes	Yes
CI score thresholds	-	Yes	Yes	Yes
verglos fix auto-remediation	-	Yes	Yes	Yes
Continuous CVE monitoring	-	Yes	Yes	Yes
Signed attestations	-	-	Planned	Planned
White-label reports	-	-	Planned	Planned
SOC 2 readiness output	-	-	-	Planned
Price	$0	$29/mo	$199/mo	$499/mo

Upgrade to Pro Discuss Studio

Privacy

Verglos runs 100% locally. Your source code is never uploaded. Anonymous scan telemetry (event ID, CLI version, Node version, platform, finding counts, project fingerprint hash, duration) fires to /api/v1/telemetry/scan after each scan. No source, no file paths, no findings text, no identity. Disable with VERGLOS_TELEMETRY=0 or --no-telemetry per invocation.

Support

Something wrong? Email support@verglos.com or open an issue at github.com/Top-Notchh-Solutions/verglos-cli.