Verify
veln verify is how you run Veln against a project tree: it walks relevant lockfiles, pulls in registry and policy signals, and emits a structured outcome — in the terminal by default.
What you see
Each package gets one of four verdicts based on its score:
- ALLOW — install proceeds normally
- WARN — install proceeds but a non-zero exit code is returned for scripts that want to surface yellow-flag packages
- BLOCK — install is refused; the offending package never reaches disk
- HOLD — temporary refusal (cooling window, pending approval, infra unavailable); HTTP 503 with
Retry-Afterand exit code 75 (EX_TEMPFAIL) so retries are obvious
Human-readable output summarizes the verdicts per your org policy. For automation, use -json so scripts, editors, or internal tools can consume the same verdict without parsing prose. The same 20+ trust signals from Gate drive the verdict.
Watch mode
Veln can re-run verify when lockfiles change (watch flows) so local development gets fast feedback without manually re-invoking the command every time.
Reachability filter
veln verify -reach scans your project source for import / require / from … import and downgrades block to warn for any package that no project file actually imports. A vulnerability in an unused transitive dependency is still surfaced but no longer stops a build — your report focuses on what your code can actually call. Works on JavaScript, TypeScript, and Python source.
One-shot allowlist baseline
veln verify -generate-allowlist persists every current warn / block / hold outcome into [policy.allowlist] in ~/.veln/config.toml. Designed for legacy-project adoption: turns hours of triage into a single command. Versioned entries — a later version bump revives surfacing on the new release.
Inline annotations
Add // veln-allow: <package-spec> <reason> (or # veln-allow: … in Python) next to a risky import. Verify honors the annotation as an allowlist entry scoped to that file and line, and the signal trail records file:line so reviewers can audit the decision in code review instead of a separate config. Spec forms: npm:lodash@4.17.20, npm:lodash, lodash@4.17.20, lodash, *:lodash. Disable with -no-inline-annotations.
Companion commands
After a verify run, three commands work on the resulting verify -json snapshot:
veln explain <pkg>— show why a blocked package is in your lockfile (direct vs transitive, which top-level deps pull it in).veln fix— propose the lowest safe version bump for each blocked package (minimizes unrelated breaking changes).-applyinvokes the package manager.veln diff a.json b.json— diff two verify snapshots so you can see what changed in your dependency posture between two points in time.
Output formats
-json emits a schema-versioned document (schema_version, exit_code, per-package decisions, signals, tiers). -markdown emits a GitHub-flavored markdown report suitable for review comments. -sbom cyclonedx / -sbom spdx embeds a software bill of materials in the JSON output.
Exit codes
Scripts typically key off the process exit code. Use flags like -fail-on-verify-error where you need “network or parse failure” to surface as failure separately from policy deny — check veln help verify for your version.