npm-pkg-audit

A CLI tool to check all dependencies and devDependencies in a package.json, fetch the latest versions from npm, compare them to installed versions, and output a CSV report.

Installation and usage

Run with npx (no install required)

npx npm-pkg-audit /path/to/package.json

Run as a global CLI

npm install -g npm-pkg-audit
npm-pkg-audit /path/to/package.json

Run from a local checkout (development)

npx /path/to/npm-pkg-audit /path/to/package.json

If no path is provided, it defaults to ./package.json in the current directory.

Output options

By default, the tool prints a copyable CSV report to the terminal:

npm-pkg-audit /path/to/package.json
# or
npx npm-pkg-audit /path/to/package.json

To write the CSV report directly to a file, use the --out option:

npm-pkg-audit /path/to/package.json --out report.csv
# or
npx npm-pkg-audit /path/to/package.json --out report.csv

Output format

The output is a CSV with the following columns:

Package,Installed Version,Latest Version,Status,Score

Status is one of:

• up-to-date when installed and latest versions are the same
• major, minor, patch (or pre-release equivalents) when an update is available
• Error when an installed or latest version cannot be determined or parsed

Installed version lookup order:

• node_modules/<pkg>/package.json version
• package-lock.json / npm-shrinkwrap.json version fallback

Score is currently:

• 1 for major-level updates
• 2 for minor-level updates
• 3 for patch-level, pre-release, or up-to-date results

Overall score summary

After the CSV output, the CLI prints an aggregate summary:

• Overall score: X.XX/3 (YY.YY%)
• Scored packages: A/B (errors/skipped ignored)

Packages that return Error (for example missing installed version or failed latest version parsing) are excluded from the aggregate score and percentage.

Testing

Run the test suite with:

npm test

The suite uses Node built-ins (node:test, node:assert) and includes:

• unit tests for status, score mapping, CSV escaping, installed-version fallback, and summary math
• lightweight CLI integration tests with mocked npm registry responses