@coderefine/cli

Multi-framework tech debt scanner for React, Vue, Svelte, and Angular. Find code quality issues, get a health score, and track improvements over time.

Quick Start

npx @coderefine/cli scan

Supported Frameworks

Features

• Multi-Framework Detection — Automatically detects React, Vue, Svelte, Angular and their meta-frameworks
• Framework-Specific Rules — Native rules for each framework's patterns and anti-patterns
• Health Score — 0-100 score based on code quality findings
• Offline First — Runs entirely locally, no network required
• Multiple Outputs — JSON, SARIF, or human-readable console
• Performance Guardrails — Configurable file size limits and parse timeouts
• Live Scan Progress — Real-time feedback showing file parsing, graph building, and rule execution progress

Usage

Basic Scan

# Scan current directory
npx @coderefine/cli scan

# Scan specific directory
npx @coderefine/cli scan --root ./my-project

# Output to console (human-readable)
npx @coderefine/cli scan -f console

# Save report to file
npx @coderefine/cli scan -o report.json

CI Mode

# Report findings without failing the build (default)
npx @coderefine/cli scan --ci -f console

# Opt-in: Exit with code 1 if any warnings or errors found
npx @coderefine/cli scan --ci --fail-on warning

# Opt-in: Exit with code 1 only for errors
npx @coderefine/cli scan --ci --fail-on error

Monorepo Support

CodeRefine automatically detects monorepos (pnpm workspaces, npm/yarn workspaces, lerna) and scans each workspace with framework-appropriate rules.

# Scan entire monorepo (default)
npx @coderefine/cli scan

# Scan only specific workspace(s)
npx @coderefine/cli scan --workspace apps/web
npx @coderefine/cli scan -w apps/web -w apps/site

# Exclude a workspace
npx @coderefine/cli scan --exclude-workspace packages/legacy

# Disable monorepo detection (treat as single project)
npx @coderefine/cli scan --no-monorepo

# List detected workspaces without scanning
npx @coderefine/cli scan --list-workspaces

Output Formats

Example Output

CodeRefine scan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Framework: Next.js (app-router)
Parsing files… 847/847
Building project graph…
Running rules… 847/847
Files scanned: 847
Health score: 64/100
Versions: scanner 0.4.0 | scoring 1.0 | rules 1.0

Findings (10 of 127)
  ERR  react/no-direct-state-mutation
       src/components/Form.tsx:23
       Do not mutate state directly

  WRN  react/no-array-index-key
       src/components/List.tsx:45
       Avoid using array index as key

  … 117 more findings (login to see all)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
See the full picture
Login to unlock all findings, track progress, and integrate with your PR workflow.

Get started: https://app.coderefine.co.uk
Or run: coderefine auth login

Guest vs Authenticated

Commands

Upload Command

Upload scan results to the CodeRefine dashboard for tracking and team visibility:

# Upload a scan report
npx @coderefine/cli upload \
  --api-key "$CODEREFINE_TOKEN" \
  --repo-name "my-org/my-repo" \
  --file coderefine-report.json

# With branch and commit info (for CI)
npx @coderefine/cli upload \
  --api-key "$CODEREFINE_TOKEN" \
  --repo-name "$GITHUB_REPOSITORY" \
  --branch "$GITHUB_REF_NAME" \
  --commit "$GITHUB_SHA" \
  --file coderefine-report.json

Scan Options

Configuration

Create a .coderefinerc.json in your project root:

{
  "rules": {
    "react/no-array-index-key": "warning",
    "nextjs/no-img-element": "error"
  },
  "include": ["src/**/*.{ts,tsx}"],
  "exclude": ["**/*.test.ts", "**/node_modules/**"]
}

Environment Variables

Requirements

• Node.js 18+

Links

• Website
• Documentation

License

MIT