CLI

The cleanlens command runs the same engine as the extension and prints the report. Code: src/cli/index.ts and src/cli/format.ts.

#Synopsis

cleanlens [path] [options]

path is the repository to analyze (default: the current directory). Only one path is allowed.

#Options

If both --json and --markdown are given, --json wins. Unknown options and invalid values print an error plus the help text and exit with code 2.

#Output formats

#Text (default)

Developers: 3
Analyzed files: 84
Analyzed commits: 500
Total violations: 212
Unattributed: 0

Alice
  Clean Code Score: 78/100
    duplication 88 · structure 70 · hygiene 82
  Analyzed Lines: 12,400
  Confidence: Highly reliable
  Contribution: 61%
  New Violations: 64
  Fixed Violations: 21
  Existing Violations: 30 (informational)
  Unattributed Violations: 0 (informational)
  Weighted Violations: 190
  Net Quality Impact: +120
  Violation Density: 15.32 / KLOC
  Active days: 88

Not ranked (insufficient analysed code)

  Bob
    Clean Code Score: 71/100
    ...

• Ranked developers first, sorted by score lowest first (who needs help most is at the top), then a "Not ranked" section.
• With --violations, a list follows: [high] Deep nesting — src/app.ts:120 (introduced/high; Alice).

#Markdown (--markdown)

A self-contained report, good as a CI artifact or a PR comment:

1. Summary table (generated time, engine, files, commits, violations, unattributed, developers).
2. The score formula and severity weights.
3. Severity breakdown (count, weight, weighted points per severity).
4. Attribution status counts.
5. Developers: one section each with a metrics table (sub-scores with density, contribution, new/fixed/existing/unattributed, weighted, net impact, density, emails, active days, first/last contribution).
6. Files with violations: per file, the count, severities, and the line numbers (first 40, then "+N more").
7. All violations: severity, rule, file:line, status, confidence, introduced by, message.

#JSON (--json)

The complete ProjectReport, pretty-printed. Use it for dashboards, diffs between runs, or your own tooling.

#Output streams

#Exit codes

--fail-on looks at every violation in the current code, whatever its attribution status. Severity order: critical > high > medium > low; so --fail-on medium fails on medium, high or critical.

#Cache

The CLI caches per-commit results in <os.tmpdir()>/cleanlens-cache/. Use --no-cache for a clean, reproducible run. See 09 — Caching & performance.

#Examples

# Human-readable report for the current repository
cleanlens

# Another repository, with the list of violations
cleanlens ../api --violations

# The Django preset instead of the config file, failing on high+
cleanlens --preset django --fail-on high

# Full history, as JSON
cleanlens --full-history --json > report.json

# Last quarter only, as Markdown
cleanlens --since "3 months ago" --markdown > q3.md

# Quick check of recent work
cleanlens --max-commits 50

#CI integration

#GitHub Actions

name: Clean Code
on: [pull_request]

jobs:
  cleanlens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # full history: attribution needs commits
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx cleanlens --markdown > cleanlens-report.md
      - uses: actions/upload-artifact@v4
        with:
          name: cleanlens-report
          path: cleanlens-report.md
      - run: npx cleanlens --fail-on critical

Notes:

• fetch-depth: 0 matters. The default shallow clone has one commit, so there would be almost nothing to attribute.
• The gate step fails the job with exit code 1; the report step before it still produces the artifact.
• If the CLI is not published to npm in your setup, build it from this repository and run node dist/cli.js.

#Pre-commit hook

#!/bin/sh
# .git/hooks/pre-commit  (chmod +x)
cleanlens --max-commits 20 --fail-on critical || {
  echo "CleanLens: critical violations found (e.g. a hard-coded secret)."
  exit 1
}

This checks the working tree, not only staged changes. Keep the threshold at critical so the hook blocks only serious problems such as secrets.

#Tracking quality over time

Save --json reports per release or per week and compare cleanCodeScore, totalViolations, and per-developer breakdown.netQualityImpact. Keep the configuration unchanged between the runs you compare.