Skip to content

Agent & CLI

Veln ships as a single Go binary (veln) for macOS, Linux, and Windows. The real-time gate routes npm, PyPI, Go, Cargo, RubyGems, NuGet, and Maven/Gradle (npm, yarn, pnpm, bun, pip, pip3, uv, pipx, go, bundle, cargo, dotnet, mvn, gradle); veln verifycovers all eight ecosystems at the lockfile. Every command supports -h / --help; most read-only commands also support -json and -markdown.

Workflow commands

The everyday surface — run these against your project.

  • verify — Evaluate lockfiles against org policy. Outputs ALLOW / WARN / BLOCK / HOLD verdicts; supports -json, -markdown, -sbom cyclonedx|spdx, -reach (reachability filter), -generate-allowlist (one-shot baseline for legacy projects), and honors inline // veln-allow: annotations. See Verify.
  • watch / agent — Long-running re-verify on lockfile change.
  • run — Pre-flight verify → run a child command behind the gate (and optionally the sandbox) → post-verify.
  • safe / sandbox — Shorthand for veln run -sandbox -with-gate -- <cmd>. Gate + OS sandbox in one word. See Sandbox.
  • daemon — Long-running supervisor: gate + local UI + watch + license recheck.
  • gate — Local HTTP proxy with two enforcement tiers: npm + PyPI get the full tarball-scoring path (integrity, OSV, license, attestation, dep-confusion); the six v2 ecosystems (Go, Cargo, Composer, RubyGems, NuGet, Maven) get URL-pattern + threat-feed + OSV blocking — known- malicious artifacts return 403 before bytes reach disk. Pass -enforce=all for everything, or a subset like -enforce=cargo,gem. See Gate.

Inspection & reporting

One-shot commands for asking questions about your dependencies.

  • package — Risk lookup for one or more packages by eco:name@version. Batched, mixed-ecosystem in a single call across all 8 supported ecosystems (npm, pypi, cargo, composer, gem, nuget, maven, go); per-package OSV vulnerabilities with IDs, threat-feed match, publish attestation (npm), declared license, cooling-window state. Reads stdin with veln package -. -fail-on-vuln / -fail-on-block for scripted gating.
  • explain — Show why a package is in the lockfile: direct vs transitive, which top-level dependencies pull it in. The fastest answer to “who pulled this in?” after a verify block.
  • diff — Diff two verify -json snapshots: added/removed packages, score deltas, decision flips, new and resolved signals.
  • fix — Propose the lowest safe version bump for each blocked package from the most recent verify, across all 8 ecosystems. With -apply, invokes the right per-ecosystem command (npm install, pip install, cargo update -p, composer require, bundle update, dotnet add package, go get). Maven/Gradle bumps require project-file edits and surface as suggestions only.
  • license — Apply [policy.license] allow / warn / block lists against every package in the lockfile. Prefix-aware SPDX matching so GPL-3.0 catches GPL-3.0-only / GPL-3.0-or-later without catching LGPL-3.0.
  • workspace — Static heuristic scan of first-party source (obfuscation, dangerous APIs, entropy). Independent of the lockfile.
  • policy — Print the effective derived policy as JSON (merged user + project config).

Package-manager wrappers

Route every npm / pip / etc. invocation through the gate and OS sandbox without changing your workflow. The wrapper flow is the recommended primary defense on developer machines.

  • wrapper — on / off / status / explain. Installs PATH shims so every package-manager invocation routes through veln.
  • shims — Low-level alias of wrapper (install / uninstall / list / explain).
  • Direct per-PM wrappers — veln npm, npx, yarn, pnpm, bun, pip, pip3, uv, pipx, go, bundle, cargo, dotnet, mvn, gradle. Each is equivalent to veln safe <pm> … — gate + OS sandbox for that one invocation.

Setup & routing

  • onboarding — Guided setup: device link, license check, daemon profile, security defaults, routing, wrapper install, optional service registration.
  • activate / device login / device refresh — Device-flow OAuth and token rotation.
  • install-env — Print or write shell snippets that route npm / pip / yarn through the gate.
  • install-config — Write package-manager config (Yarn Berry npm-compat) for the gate.

Operational

  • service — install / uninstall / start / stop / status as launchd (macOS) / systemd-user (Linux) / SCM (Windows).
  • status — One-screen agent status: daemon, gate, license, threat-feed, integrity. -json for automation.
  • doctor — Reachability, certs, env, license freshness, time skew.
  • logs — Tail the daemon log (-tail, -follow, -since).
  • update — Self-update: download signed release, verify ed25519 sidecar, downgrade- guard, atomic swap on all 3 OSes, restart the service.
  • uninstall — Remove ~/.veln and the shell blocks.
  • config — Validate / sign / verify the TOML.
  • ui — Local web UI on 127.0.0.1:4875 for findings + allowlisting.
  • completion — Shell completion (bash, zsh, fish, pwsh).
  • drivers — List supported ecosystem drivers (npm, Python).

License and policy

The CLI needs a valid org license to enforce in normal mode — org-level entitlements (tier, seat count, enabled features) come from the signed license the agent activates against the cloud. Detailed policy (score thresholds, enforce modes, allowlists, license rules) is configured per machine in ~/.veln/config.toml and (optionally) per project in veln.toml. See Configuration.

Output formats

Every read-only command supports -json (schema-versioned) for scripts and tooling, and -markdown for review comments. -json and -markdown are mutually exclusive.

Help

Run veln help for the full list, and veln <command> -h for per-command flags and defaults on your build.

← Documentation overview