@veriva/cli

AI Code Governance from your terminal. Analyze diffs and PRs for security vulnerabilities, hallucinated dependencies (slopsquatting), AI-generated code patterns, and quality issues — with an A–F trust score.

Install

npm install -g @veriva/cli
# or
pnpm add -g @veriva/cli

Requires Node.js ≥22.

Zero config for local-only scanning. Remote PR analysis requires authentication — run veriva login, or set the VERIVA_TOKEN env var in CI.

Quick start

# Scan your current git diff (local-only, no auth needed)
veriva scan

# Authenticate for remote PR analysis.
# CI environments can set VERIVA_TOKEN instead of running login.
veriva login

# Scan a remote PR
veriva scan --pr 123
veriva scan --pr owner/repo/123

# SARIF output for GitHub Code Scanning
veriva scan --sarif --output veriva.sarif

# Repository health checks (lockfile, vulns, security policy)
veriva health

# Validate in-repo governance hooks
veriva policy lint

Commands

• veriva analyze [PATH]
• veriva config get KEY
• veriva config init
• veriva config list
• veriva config set KEY VALUE
• veriva config telemetry ACTION
• veriva health
• veriva help [COMMAND]
• veriva login
• veriva logout
• veriva policy lint
• veriva rule new NAME
• veriva rule test
• veriva rules
• veriva scan [PATH]
• veriva status
• veriva update [CHANNEL]
• veriva version

veriva analyze [PATH]

Analyze code for AI patterns, security issues, and supply chain risks

USAGE
  $ veriva analyze [PATH] [-p <value>] [-f <value>] [--local] [--json] [--agent] [--sarif] [-o <value>]
    [--fail-on A|B|C|D|F]

ARGUMENTS
  [PATH]  Path to a diff file (optional)

FLAGS
  -f, --file=<value>      Path to a .patch or .diff file
  -o, --output=<value>    Write output to a file instead of stdout
  -p, --pr=<value>        GitHub PR to scan (e.g., 123 or owner/repo/123)
      --agent             Output results as agent JSON (schema-versioned, severity_score, fingerprint id, provenance)
                          for AI-agent consumers
      --fail-on=<option>  [default: D] Exit with code 1 if trust score is below this threshold
                          <options: A|B|C|D|F>
      --json              Output results as JSON
      --local             Force local-only analysis (skip API, Layer 1 only)
      --sarif             Output results in SARIF 2.1.0 format (for GitHub Code Scanning)

DESCRIPTION
  Analyze code for AI patterns, security issues, and supply chain risks

EXAMPLES
  $ veriva analyze

  $ veriva analyze --pr 123

  $ veriva analyze --pr owner/repo/123

  $ veriva analyze --file diff.patch

  $ veriva analyze --sarif --output results.sarif

  $ veriva analyze --json | jq .findings

  $ veriva analyze --agent | jq .findings

  $ veriva analyze --fail-on D

veriva config get KEY

Read a persisted CLI config value (apiUrl, telemetry)

USAGE
  $ veriva config get KEY

ARGUMENTS
  KEY  Config key — one of: apiUrl, telemetry

DESCRIPTION
  Read a persisted CLI config value (apiUrl, telemetry)

EXAMPLES
  $ veriva config get apiUrl

  $ veriva config get telemetry

veriva config init

Create a .veriva.yml configuration file

USAGE
  $ veriva config init [--force] [-d <value>]

FLAGS
  -d, --dir=<value>  [default: .] Directory to create config in
      --force        Overwrite existing .veriva.yml

DESCRIPTION
  Create a .veriva.yml configuration file

EXAMPLES
  $ veriva config init

  $ veriva config init --force

  $ veriva config init --dir packages/api

veriva config list

List every persisted CLI config value

USAGE
  $ veriva config list

DESCRIPTION
  List every persisted CLI config value

EXAMPLES
  $ veriva config list

  # Pipe-friendly: load the config into a shell

  eval "$(veriva config list)"

veriva config set KEY VALUE

Persist a CLI config value (apiUrl, telemetry)

USAGE
  $ veriva config set KEY VALUE

ARGUMENTS
  KEY    Config key — one of: apiUrl, telemetry
  VALUE  Value to persist

DESCRIPTION
  Persist a CLI config value (apiUrl, telemetry)

EXAMPLES
  $ veriva config set apiUrl https://beta-api.veriva.dev

  $ veriva config set apiUrl https://api.veriva.dev

  $ veriva config set telemetry off

veriva config telemetry ACTION

Enable, disable, or show CLI telemetry opt-in status

USAGE
  $ veriva config telemetry ACTION

ARGUMENTS
  ACTION  (on|off|status) on | off | status

DESCRIPTION
  Enable, disable, or show CLI telemetry opt-in status

EXAMPLES
  $ veriva config telemetry on

  $ veriva config telemetry off

  $ veriva config telemetry status

  VERIVA_TELEMETRY=0 veriva scan

  DO_NOT_TRACK=1 veriva scan

veriva health

Run repository health checks (lockfile, vulnerabilities, security policy)

USAGE
  $ veriva health [--json] [-d <value>]

FLAGS
  -d, --dir=<value>  [default: .] Directory to check (defaults to current directory)
      --json         Output results as JSON (pipe-safe — no ANSI escapes)

DESCRIPTION
  Run repository health checks (lockfile, vulnerabilities, security policy)

EXAMPLES
  $ veriva health

  $ veriva health --json | jq .findings

  $ veriva health --dir packages/api

veriva help [COMMAND]

Display help for veriva.

USAGE
  $ veriva help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for veriva.

veriva login

Authenticate with Veriva

USAGE
  $ veriva login [-t <value>]

FLAGS
  -t, --token=<value>  [env: VERIVA_TOKEN] Authenticate directly with an API token (env: VERIVA_TOKEN — for CI
                       environments)

DESCRIPTION
  Authenticate with Veriva

EXAMPLES
  $ veriva login

  $ veriva login --token vr_abc123...

  VERIVA_TOKEN=vr_abc... veriva login

veriva logout

Clear stored Veriva credentials

USAGE
  $ veriva logout

DESCRIPTION
  Clear stored Veriva credentials

EXAMPLES
  $ veriva logout

  # CI: clear inherited credentials before running an auth-required step

  $ veriva logout && veriva login --token "$VERIVA_TOKEN"

veriva policy lint

Validate .veriva/rules/*.yml governance hooks

USAGE
  $ veriva policy lint [-d <value>] [--json]

FLAGS
  -d, --dir=<value>  [default: .] Repository directory to lint
      --json         Output as JSON

DESCRIPTION
  Validate .veriva/rules/*.yml governance hooks

EXAMPLES
  $ veriva policy lint

  $ veriva policy lint --json | jq .errors

  $ veriva policy lint --dir packages/api

veriva rule new NAME

Scaffold a new in-repo rule (.veriva/rules/.yml)

USAGE
  $ veriva rule new NAME [--type rule|llm|shell|webhook] [--dir <value>] [--force]

ARGUMENTS
  NAME  Rule name (kebab-case). Becomes .veriva/rules/<name>.yml

FLAGS
  --dir=<value>    [default: .] Repo root (rule is written to <dir>/.veriva/rules/<name>.yml). Defaults to cwd.
  --force          Overwrite an existing file at the target path
  --type=<option>  [default: rule] Rule type
                   <options: rule|llm|shell|webhook>

DESCRIPTION
  Scaffold a new in-repo rule (.veriva/rules/<name>.yml)

EXAMPLES
  $ veriva rule new no-todos --type=rule

  $ veriva rule new public-endpoints --type=llm

  $ veriva rule new license-scanner --type=shell

  $ veriva rule new soc2-audit --type=webhook

  $ veriva rule new my-rule --type=rule --dir=packages/api

veriva rule test

Run an in-repo rule against a diff offline (no API call)

USAGE
  $ veriva rule test --rule <value> [--diff <value>]

FLAGS
  --diff=<value>  Diff source: a file path, "-" for stdin, or omit for `git diff HEAD`
  --rule=<value>  (required) Path to the rule YAML (.veriva/rules/<name>.yml)

DESCRIPTION
  Run an in-repo rule against a diff offline (no API call)

EXAMPLES
  $ veriva rule test --rule .veriva/rules/no-todos.yml

  $ veriva rule test --rule .veriva/rules/foo.yml --diff change.patch

  git diff HEAD~3 | veriva rule test --rule .veriva/rules/foo.yml --diff -

veriva rules

List all Veriva detection rules

USAGE
  $ veriva rules [--category SECURITY|QUALITY|PRACTICES|SUPPLY_CHAIN|DOCUMENTATION] [--layer 0|1|2|3]
    [--severity CRITICAL|HIGH|MEDIUM|LOW|INFO] [--json]

FLAGS
  --category=<option>  Filter by category
                       <options: SECURITY|QUALITY|PRACTICES|SUPPLY_CHAIN|DOCUMENTATION>
  --json               Output as JSON
  --layer=<option>     Filter by analysis layer (0-3)
                       <options: 0|1|2|3>
  --severity=<option>  Filter by minimum severity
                       <options: CRITICAL|HIGH|MEDIUM|LOW|INFO>

DESCRIPTION
  List all Veriva detection rules

EXAMPLES
  $ veriva rules

  $ veriva rules --category SECURITY

  $ veriva rules --severity HIGH --json

  $ veriva rules --layer 2

veriva scan [PATH]

Scan code for AI patterns, security issues, and supply chain risks

USAGE
  $ veriva scan [PATH] [-p <value>] [-f <value>] [--local] [--json] [--agent] [--sarif] [-o <value>]
    [--fail-on A|B|C|D|F]

ARGUMENTS
  [PATH]  Path to a diff file (optional)

FLAGS
  -f, --file=<value>      Path to a .patch or .diff file
  -o, --output=<value>    Write output to a file instead of stdout
  -p, --pr=<value>        GitHub PR to scan (e.g., 123 or owner/repo/123)
      --agent             Output results as agent JSON (schema-versioned, severity_score, fingerprint id, provenance)
                          for AI-agent consumers
      --fail-on=<option>  [default: D] Exit with code 1 if trust score is below this threshold
                          <options: A|B|C|D|F>
      --json              Output results as JSON
      --local             Force local-only analysis (skip API, Layer 1 only)
      --sarif             Output results in SARIF 2.1.0 format (for GitHub Code Scanning)

DESCRIPTION
  Scan code for AI patterns, security issues, and supply chain risks

EXAMPLES
  $ veriva scan

  $ veriva scan --pr 123

  $ veriva scan --json | jq .findings

veriva status

Check authentication status and API connectivity

USAGE
  $ veriva status

DESCRIPTION
  Check authentication status and API connectivity

EXAMPLES
  $ veriva status

  # CI: confirm token-based auth resolves before kicking off scans

  VERIVA_TOKEN=vr_abc... veriva status

veriva update [CHANNEL]

update the veriva CLI

USAGE
  $ veriva update [CHANNEL] [--force |  | [-a | -v <value> | -i]] [-b ]

FLAGS
  -a, --available        See available versions.
  -b, --verbose          Show more details about the available versions.
  -i, --interactive      Interactively select version to install. This is ignored if a channel is provided.
  -v, --version=<value>  Install a specific version.
      --force            Force a re-download of the requested version.

DESCRIPTION
  update the veriva CLI

EXAMPLES
  Update to the stable channel:

    $ veriva update stable

  Update to a specific version:

    $ veriva update --version 1.0.0

  Interactively select version:

    $ veriva update --interactive

  See available versions:

    $ veriva update --available

veriva version

USAGE
  $ veriva version [--json] [--verbose]

FLAGS
  --verbose  Show additional information about the CLI.

GLOBAL FLAGS
  --json  Format output as json.

FLAG DESCRIPTIONS
  --verbose  Show additional information about the CLI.

    Additionally shows the architecture, node version, operating system, and versions of plugins that the CLI is using.

Run veriva <command> --help for all flags.

veriva scan is the public happy path. veriva analyze is retained for compatibility and exposes the same scan flags.

CI usage

# .github/workflows/veriva.yml
- uses: veriva-ai/analyze-action@v1
  with:
    sarif-file: veriva.sarif
    fail-on-critical: true

Or call the CLI directly:

export VERIVA_TOKEN=${{ secrets.VERIVA_TOKEN }}

veriva scan --pr ${{ github.event.pull_request.number }} \
  --sarif --output veriva.sarif --fail-on C

Plans

• Hobby — Layer 1 static analysis (AI patterns, slopsquatting, security heuristics). Free.
• Pro — Adds Layer 2 AI review and Aria chat. $29/dev/mo.
• Ultra / Enterprise — Adds Layer 3 auto-fix and SLAs. veriva.dev/pricing

Telemetry

The CLI ships with opt-in anonymous usage telemetry. You are prompted the first time you run veriva login or veriva scan. To change your choice later:

veriva config telemetry status
veriva config telemetry on
veriva config telemetry off

# One-command/session kill switches
VERIVA_TELEMETRY=0 veriva scan
DO_NOT_TRACK=1 veriva scan
VERIVA_TELEMETRY_DISABLED=1 veriva scan

We never send source code, file paths, repository names, diff contents, or email addresses.

Error message format

For contributors. Every command-level error follows the canonical 3-rule shape via lib/error-format.ts:

import { formatErrorMessage } from '../lib/error-format.js';

this.error(
  formatErrorMessage({
    summary: 'Rule file not found: foo.yml',
    hint: [
      'Confirm the path: `ls foo.yml`',
      'Scaffold a starter with `veriva rule new <name>`',
    ],
    ref: '--rule',
  }),
  { exit: 1 },
);

1. summary — one-line statement of what failed, plain English (no implementation jargon, no full stack traces).
2. hint — what the user can do next: a concrete command, env var, or operational change. Single string for one hint; string[] for multiple (rendered as a bulleted "Try one of:" list).
3. ref — the relevant flag, env var, config key, or doc link the hint targets. Optional but encouraged.

For network / HTTP errors, use the sibling helpers in lib/diagnostics.ts (diagnoseFetchError, diagnoseHttpResponse, formatDiagnosis). They produce the same shape with category-specific defaults.

Fixture tests in src/lib/error-format.test.ts pin every helper output combination — adding a hint format or a new ref pattern means updating the snapshots there.

Links

• Website: veriva.dev
• Issues: github.com/veriva-ai/veriva/issues
• Support: [email protected]

License

Apache-2.0. See LICENSE.