license-check-cli

Scan npm project dependencies and flag copyleft / restrictive licenses.
Zero npm dependencies — pure Node.js built-ins only.

Install

npm install -g license-check-cli

Usage

license-check [options] [directory]

Run in your project root (or pass the directory):

license-check                    # scan current directory
license-check ./my-project       # scan specific directory
license-check --no-dev           # skip devDependencies
license-check --json             # machine-readable JSON output
license-check --deny GPL-3.0,AGPL-3.0   # fail on specific licenses
license-check --allow LGPL-2.1          # whitelist a license

Options

| Flag | Description | |------|-------------| | [directory] | Project root with package.json (default: .) | | --allow <licenses> | Comma-separated licenses to whitelist (suppress warnings) | | --deny <licenses> | Comma-separated licenses that explicitly trigger failure | | --json | Output machine-readable JSON | | --no-dev | Skip devDependencies | | --no-color | Disable colored output | | -h, --help | Show help |

Risk Levels

| Level | Licenses | What it means | |-------|----------|---------------| | HIGH | GPL-2.0, GPL-3.0, AGPL-3.0, SSPL-1.0, … | Strong copyleft — using these may require you to open-source your entire project | | MEDIUM | LGPL-2.1, LGPL-3.0, MPL-2.0, EUPL-1.2, … | Weak copyleft — linking/modification restrictions apply | | low | MIT, ISC, BSD-*, Apache-2.0, … | Permissive — generally safe for commercial use | | unknown | Missing/unlicensed packages | No license declared — treat with caution |

Exit Codes

| Code | Meaning | |------|---------| | 0 | All clear — no flagged licenses | | 1 | Flagged licenses found (HIGH/MEDIUM risk or explicitly denied) | | 2 | Error (directory not found, no package.json, etc.) |

Examples

Basic scan

$ license-check
license-check — scanning /home/user/my-app

Package         | Version | License    | Risk
----------------|---------|------------|-------
express         | 4.18.2  | MIT        | low
lodash          | 4.17.21 | MIT        | low
some-gpl-lib    | 1.0.0   | GPL-3.0    | HIGH

Scanned: 3 packages   Flagged: 1

Flagged packages:
  ✖ [email protected] — GPL-3.0 [HIGH]

JSON output (CI/CD integration)

$ license-check --json | jq '.flagged'
2

{
  "scanned": 42,
  "flagged": 1,
  "exit_code": 1,
  "packages": [
    {
      "name": "some-gpl-lib",
      "version": "1.0.0",
      "license": "GPL-3.0",
      "risk": "HIGH",
      "flagged": true
    }
  ]
}

CI/CD usage

# GitHub Actions example
- name: Check licenses
  run: npx license-check-cli --no-dev --deny GPL-3.0,AGPL-3.0

Allow specific licenses

# You've reviewed LGPL-2.1 usage and it's acceptable in your project
license-check --allow LGPL-2.1

How it works

1. Reads your project's package.json
2. If node_modules/ exists, scans each installed package's own package.json for the license field (catches transitive dependencies too)
3. If node_modules/ is absent, falls back to listing declared deps with UNKNOWN license (useful in CI before npm install)
4. Classifies each license by risk level
5. Reports a summary table and exits with the appropriate code

License

MIT