licenseleak

Local-first license compliance scanner. Two modes, one CLI:

• Offline (default): parses your manifests and lockfiles (package.json, requirements.txt, go.mod, Cargo.lock, Gemfile.lock, composer.lock) and classifies every declared dependency by SPDX license family. No source code is read, no network requests are made.
• Hosted full-source scan (--remote, or any https://github.com/... URL): uploads (or fetches) the working tree to the LicenseLeak hosted scanner, which runs deep AST-shingle fingerprinting against a copyleft corpus to find copy-pasted snippets (the bits Copilot, Cursor, and friends quietly added) and ships back a SHA-256 signed PDF.

The default offline mode does not detect copy-pasted source. For that, use --remote or sign in at https://licenseleak.com.

Quickstart (30 seconds)

# Default: offline scan of your manifests/lockfiles. No signup, no upload,
# no network requests. Will NOT detect copy-pasted source — use --remote
# (or a GitHub URL) for that.
npx licenseleak scan .

# Hosted full-source scan of a public GitHub repo (snippet matching +
# signed PDF). Requires an API key.
npx licenseleak login
npx licenseleak scan https://github.com/your-org/your-repo

# Hosted full-source scan of a local checkout (uploads a gzipped tarball).
npx licenseleak scan . --remote

scan exits with code 1 if any critical finding is present (override with --fail-on high|medium|low|none), so you can drop it into a pre-commit hook or any CI without copy-pasting YAML.

Commands

| Command | Description | | --- | --- | | licenseleak scan <path-or-url> | Scan a local path (default) or a https://github.com/... URL. | | licenseleak login | Save an API key to ~/.licenseleak/config.json (mode 0600). | | licenseleak logout | Remove the saved API key. | | licenseleak whoami | Print the account, plan, and credit balance for the saved key. | | licenseleak --help | Full flag reference. |

Flags

• --remote — force a remote scan even when given a local-looking path.
• --branch <name> — branch to scan (remote only).
• --format <text|json> — emit a structured JSON report for piping into other tooling. Same shape as the hosted API's findings response.
• --fail-on <critical|high|medium|low|none> — exit-code threshold. Default critical.
• --no-hints — suppress the one-line "scanned offline" hint printed after a successful local scan in text mode. Useful for CI logs and power users.

Excluding files from upload

This section applies only to remote uploads — licenseleak scan <path> --remote. (The default offline scan <path> reads only manifests and lockfiles, never the rest of your tree, and uploads nothing.) Remote uploads walk your working directory and apply two ignore files:

1. .gitignore — read from the repo root, matching git check-ignore semantics (anchoring, dir/ directory-only, !negation).
2. .licenseleakignore — same syntax as .gitignore, additive on top. Use it to exclude paths you want git to track but don't want LicenseLeak to scan (e.g. vendored fixtures, generated test snapshots, one specific package in a monorepo). A !pattern line can re-include a path that .gitignore would have excluded.

The CLI prints a one-line summary to stderr after packing:

  excluded 142 file(s) by .gitignore, 7 by .licenseleakignore

The active .licenseleakignore patterns and per-source counts are sent with the upload, persisted on the scan record, embedded in the signed manifest, and shown under "Exclusions" in the public HTML / PDF report so anyone reviewing the report can see exactly what scope you scanned.

Auth

The CLI reads its API key from, in order:

1. LICENSELEAK_API_KEY environment variable.
2. ~/.licenseleak/config.json (created by licenseleak login, file mode 0600).

Generate a key from the Settings → API keys page. The key is sent as Authorization: Bearer ll_live_….

Network access

The default licenseleak scan <path> command is fully offline: it reads manifests and lockfiles from disk, classifies them locally, and prints the result. No source code, dependency list, telemetry, or update check is sent anywhere.

Outbound HTTP requests are made only by the following commands and flags:

| Trigger | Endpoint | What is sent | | --- | --- | --- | | licenseleak scan https://github.com/... | Hosted API (POST /api/scans) | The repo URL and optional branch name. | | licenseleak scan <path> --remote | Hosted API (POST /api/scans/upload) | A gzipped tarball of your working directory, plus the active .licenseleakignore patterns and per-source excluded-file counts (sent as X-Licenseleak-Ignore-Patterns / X-Licenseleak-Excluded-Counts headers and embedded in the signed manifest). | | licenseleak whoami | Hosted API (GET /api/me) | Your API key, to look up account / plan / credits. |

licenseleak login and licenseleak logout make no network calls — they only read/write ~/.licenseleak/config.json (mode 0600). The saved key is then used by the commands above.

That is the complete list. No other command, flag, or code path in this CLI opens a network connection. There is no telemetry, no auto-update check, no crash reporter, no analytics beacon.

Local vs remote

• Local (default for paths): walks the directory's manifests and lockfiles for npm, pip, go, cargo, ruby, and php; classifies each dependency by SPDX license family; reports any non-permissive match. No source code or telemetry is uploaded anywhere. Best for a fast pre-commit sniff test.
• Remote (default for https:// URLs, or --remote): submits the repo URL to the hosted scanner, which performs deep AST fingerprinting against a copyleft corpus and produces a signed PDF. Polls until terminal and prints the same colorized table.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Scan completed and no finding met the --fail-on threshold. | | 1 | Scan completed and at least one finding met the threshold. | | 2 | Scanner error, auth failure, invalid arguments. |

License

Apache-2.0 — see LICENSE.

Source of truth

This repository (licenseleak/cli) is a one-way release mirror of packages/cli/ from the LicenseLeak monorepo. Each tagged release on npm lands here as a single commit (with a back-reference to the upstream commit SHA), and a matching vX.Y.Z git tag.

• Issues and discussions: open them on this repo — https://github.com/licenseleak/cli/issues
• Pull requests: also welcome on this repo. Accepted PRs are replayed upstream by the maintainers and shipped in the next release.
• The hosted scanner, similarity engine, benchmark corpus, and signed- report pipeline live in the private monorepo and are not part of this package — the CLI is a thin client that calls the LicenseLeak API for remote scans and runs a deterministic SPDX classifier locally.