vis inspect

vis inspect <pkg>[@<spec>] runs the pre-install marshall pipeline against a single package and reports its findings without touching the lockfile or node_modules. Use it to vet a third-party dependency before a vis add, or in code review to surface red flags on a proposed addition.

Usage

vis inspect <package>[@<spec>] [options]

<spec> may be a version (1.2.3), a semver range (^18), or a dist-tag (latest, next). Defaults to latest when omitted.

Quick examples

vis inspect express                       # latest dist-tag
vis inspect lodash@4.17.21                # exact pin
vis inspect react@^18                     # resolve range, inspect best match
vis inspect express --json                # JSON for CI integration
vis inspect express --strict              # exit non-zero on warnings too
vis inspect express --only author,downloads
vis inspect express --only signatures     # signatures are off by default; opt in here

Marshalls

Every marshall is identical to the one run during vis add / vis install / vis update:

Options

--json

Emit findings as a JSON document instead of the human-readable table:

vis inspect express --json | jq '.findings[] | select(.severity == "error")'

The schema is:

{
    errors: MarshallFinding[];
    warnings: MarshallFinding[];
    findings: MarshallFinding[];        // errors + warnings, stable order
    summary: { errorCount: number; warningCount: number };
}

--strict

Exit non-zero on any finding — warnings included. Default behavior exits 0 when only warnings fire, mirroring the auto-continue countdown semantics on the install path.

--only <list>

Run only the listed marshalls (comma-separated). Known names: author, provenance, s1ngularity, newBin, metadata, downloads, expiredDomains, signatures, archivedRepo.

vis inspect lodash --only author,signatures

Signatures are opt-in. When --only is omitted, signatures is skipped — matching the pre-install pipeline default in vis add / vis update. npm's signing-key coverage still produces noisy warnings on legitimate packages, so the marshall only runs when you explicitly request it via --only signatures.

Exit codes

Environment variables

Every MARSHALL_DISABLE_* toggle and MARSHALL_DISABLE_ALL documented in Wrap your package manager applies here as well.

See also

• vis add — pre-install pipeline that includes these marshalls.
• vis audit — installed-set vulnerability scan.
• Wrap your package manager — alias your PM through vis.