@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

| UI Framework | Meta-Framework | Capability Level | |--------------|----------------|------------------| | React | Next.js | L5 (Full) | | Vue 3 | Nuxt 3 | L4-L5 | | Svelte | SvelteKit | L4 | | Angular | — | L4 |

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

| Format | Flag | Description | |--------|------|-------------| | JSON | -f json (default) | Full scan results as JSON | | Console | -f console | Human-readable summary | | SARIF | -f sarif | Static Analysis Results Interchange Format |

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

| Feature | Guest | Free (logged in) | |---------|-------|------------------| | Health score | ✓ Full | ✓ Full | | Findings preview | 10 findings | Unlimited | | Offline scans | ✓ | ✓ | | Upload & tracking | — | ✓ |

Commands

| Command | Description | |---------|-------------| | scan | Run a local scan | | upload | Upload scan results to CodeRefine dashboard | | init | Create config file in current directory | | doctor | Diagnose environment and configuration | | auth login | Login to unlock full features | | auth logout | Remove stored credentials | | auth status | Check authentication status |

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

| Flag | Description | |------|-------------| | --api-key <key> | Organisation API key (required) | | --api-url <url> | API base URL (default: https://api.coderefine.co.uk) | | -f, --file <path> | Scan JSON file (or pipe via stdin) | | --repository-id <uuid> | Existing repository ID | | --repo-name <name> | Repository name (e.g., org/repo) | | --branch <name> | Branch label | | --commit <sha> | Commit SHA |

Scan Options

| Flag | Description | |------|-------------| | -r, --root <dir> | Project root directory (default: cwd) | | -f, --format <fmt> | Output: json (default), console, sarif | | -o, --output <file> | Write report to file | | --ci | CI mode (non-interactive output) | | --fail-on <level> | Exit 1 if findings at level: info, warning, error (default: never fail) | | --plan | Include refactor plan (requires login) | | -w, --workspace <path> | Scan only specific workspace(s) — repeatable | | --exclude-workspace <path> | Exclude workspace(s) from scan — repeatable | | --no-monorepo | Disable monorepo detection, treat as single project | | --list-workspaces | List detected workspaces and exit (no scan) |

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

| Variable | Description | |----------|-------------| | CODEREFINE_TOKEN | API token for upload command | | CODEREFINE_API_URL | Override API URL (default: https://api.coderefine.co.uk) |

Requirements

• Node.js 18+

Links

• Website
• Documentation
• v0.6.0 release notes (in this monorepo): docs/release-notes/cli-v0.6.0.md

License

MIT