Quick Start

npx @sprinno/scan

That's it. First run takes ~30 seconds for setup, then scans in 10–30s depending on repo size.

What It Does

Sprinno is the SAT for codebases , a standardized, reproducible quality score across 5 engineering pillars. It produces a 0–100 score, tracks your progress over time, and outputs a machine-readable .sprinno.json manifest. It also functions as a grading system for agentic coding: use npx @sprinno/scan fix to auto-heal findings with your own AI coding agent.

| Pillar | What It Measures | |--------|--------|------------------| | Code Health | Security vulnerabilities, cyclomatic complexity, test coverage, dependency health | | Process Maturity | CI/CD pipelines, code review practices, linting, pre-commit hooks, release management | | Architecture | Modularity, coupling, infrastructure-as-code, containerization, dependency management | | Team Dynamics | Bus factor, collaboration patterns, contribution equity, onboarding readiness, knowledge distribution | | Business Alignment | Deploy readiness, tech debt management, feature velocity, incident response, release frequency |

Scanners

Under the hood, 10 independent scanners run in parallel:

| Scanner | Pillar | Checks | |---------|--------|--------| | Security | Code Health | Leaked secrets, dangerous functions, weak crypto, SQL/XSS/command injection, security headers, .env.example | | Complexity | Code Health | Cyclomatic complexity, code duplication, large files | | Testing | Code Health | Test file count, test-to-code ratio, coverage %, CI config, SAST in pipeline, pre-commit hooks | | Dependencies | Code Health + Architecture | Lock file, engines field, total dependency count, freshness | | Git | Process Maturity | Commit frequency, contributor count, bus factor, repo age | | Process Maturity | Process Maturity | Maturity level, pre-commit hooks, issue templates | | Infrastructure | Architecture | Dockerfile, Kubernetes, Terraform, IaC maturity level | | Resilience | Resilience | Health endpoints, monitoring integrations, circuit breakers, rate limiting, graceful shutdown, error boundaries | | Documentation | Documentation | README presence & length, CONTRIBUTING, CHANGELOG, API docs, architecture docs, onboarding guide, inline doc ratio | | Metadata | (context) | Language, framework, file count, line count , used for calibration context |

All scanners are static analysis only , no code execution, no network calls to your infrastructure, no build step required.

Commands

Default: Full Scan

npx @sprinno/scan

Runs all scanners, prints a terminal report, and saves .sprinno.json.

All Options

npx @sprinno/scan [command] [options]

| Command | Description | |---------|-------------| | scan (default) | Run a full quality scan | | fix | Auto-fix findings using your installed coding agent | | setup | Re-run onboarding (change stage, sector, team size) | | connect | Link to Sprinno Cloud for percentiles & calibrated scores | | forget | Delete all server-side scan history (GDPR right to erasure) |

| Flag | Description | Default | |------|-------------|---------| | --json | Output .sprinno.json only (no terminal report) | - | | --ci | CI mode , exit with non-zero code if below threshold | - | | --fail-below <score> | Minimum overall score (used with --ci) | 60 | | --card | Export a shareable SVG score card (.sprinno-score.svg) | - | | --stage <stage> | Override company stage for this scan | from config | | --format <format> | Output format: terminal, json, sarif | terminal |

Examples

# Full scan with terminal report
npx @sprinno/scan

# JSON output only
npx @sprinno/scan --json

# CI mode with quality gate
npx @sprinno/scan --ci --fail-below 60

# Export SVG badge/card
npx @sprinno/scan --card

# Override stage context
npx @sprinno/scan --stage series-a

Output

.sprinno.json

Every scan generates a .sprinno.json file , a machine-readable quality manifest:

{
  "$schema": "https://schema.sprinno.com/quality/v1",
  "version": 1,
  "overall": 67.4,
  "pillars": {
    "codeHealth": { "score": 72.8 },
    "processMaturity": { "score": 61.3 },
    "architecture": { "score": 68.0 },
    "teamDynamics": { "score": 54.9 },
    "businessAlignment": { "score": 70.1 }
  },
  "context": {
    "stage": "seed",
    "sector": "fintech",
    "teamSize": "small"
  }
}

AI coding tools, IDE extensions, and CI pipelines can read this file to understand your codebase quality at a glance.

Terminal Report

  🔍 Sprinno Code Quality Scan
  ─────────────────────────────────────────────

  Overall Score: 67.4 / 100

  ┌─────────────────────┬───────┬──────────────────────────────┐
  │ Pillar              │ Score │ Rating                        │
  ├─────────────────────┼───────┼──────────────────────────────┤
  │ Code Health         │  72.8 │ ████████████████░░░░ Good      │
  │ Process Maturity    │  61.3 │ ████████████░░░░░░░░ Fair      │
  │ Architecture        │  68.0 │ █████████████░░░░░░░ Good      │
  │ Resilience          │  54.9 │ ███████████░░░░░░░░░ Fair      │
  │ Documentation       │  70.1 │ ██████████████░░░░░░ Good      │
  └─────────────────────┴───────┴──────────────────────────────┘

  ⚠️  3 findings:
     • No monitoring/observability integration detected
     • Test coverage at 38% (below 60% threshold)
     • Low bus factor , knowledge concentrated in few contributors

Score Card (SVG)

Use --card to generate .sprinno-score.svg , embed it in your README, pitch decks, or share with investors.

Scoring

Rating Bands

| Score | Rating | |-------|--------| | 80–100 | 🟢 Excellent | | 65–79 | 🔵 Good | | 50–64 | 🟡 Fair | | 35–49 | 🟠 Needs Work | | 0–34 | 🔴 Critical |

How It Works

The CLI uses hand-tuned scoring weights across the 5 pillars. Each pillar has sub-metrics that are individually scored 0–100, then combined using weighted averages.

Want more accurate scores? Sprinno Cloud uses Latent Capability Scoring (LCS) , a proprietary calibration algorithm trained on thousands of anonymized scans. LCS determines which metrics genuinely distinguish strong engineering from weak engineering at each company stage. Run npx @sprinno/scan connect to upgrade.

CI/CD Integration

GitHub Actions (inline)

name: Quality Gate
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npx --yes @sprinno/scan --ci --fail-below 60
        env:
          SPRINNO_STAGE: seed
          SPRINNO_SECTOR: fintech
          SPRINNO_TEAM_SIZE: small
          SPRINNO_ACCEPT_TERMS: 'true'

GitHub Action (reusable)

name: Quality Gate
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: sprinno/scan@v1
        id: scan
        with:
          fail-below: '60'
          stage: 'seed'
          sector: 'fintech'
          team-size: 'small'
      - run: echo "Score: ${{ steps.scan.outputs.overall-score }}"

Action Inputs

| Input | Description | Default | |-------|-------------|---------| | fail-below | Minimum overall score to pass (0–100). Set to 0 to never fail. | 0 | | stage | pre-seed, seed, series-a, series-b-plus, oss, enterprise | seed | | sector | fintech, saas, ai-ml, consumer, healthcare, devtools, ecommerce, other | saas | | team-size | solo, small, medium, large, very-large | small | | output-format | terminal, json | terminal |

Action Outputs

| Output | Description | |--------|-------------| | overall-score | Overall quality score (0–100) | | code-health | Code Health pillar score | | process-maturity | Process Maturity pillar score | | architecture | Architecture pillar score | | resilience | Resilience pillar score | | documentation | Documentation pillar score |

GitLab CI

quality-gate:
  image: node:20
  script:
    - npx --yes @sprinno/scan --ci --fail-below 60
  variables:
    SPRINNO_STAGE: seed
    SPRINNO_SECTOR: saas
    SPRINNO_TEAM_SIZE: small
    SPRINNO_ACCEPT_TERMS: 'true'

Configuration

First-Run Onboarding

On first run, Sprinno asks you:

1. Company stage , pre-seed, seed, series-a, series-b+, oss, enterprise
2. Sector , fintech, saas, ai-ml, consumer, healthcare, devtools, ecommerce, other
3. Team size , solo, small, medium, large, very-large

This context calibrates expectations. A solo pre-seed project isn't judged the same as a Series B fintech.

Environment Variables

Skip interactive prompts in CI by setting:

| Variable | Description | |----------|-------------| | SPRINNO_STAGE | Company stage | | SPRINNO_SECTOR | Sector | | SPRINNO_TEAM_SIZE | Team size | | SPRINNO_CI | Set to true to enable CI mode | | SPRINNO_ACCEPT_TERMS | Set to true to accept terms non-interactively |

.sprinnorc

After onboarding, config is saved locally. You can edit it directly:

{
  "termsAccepted": true,
  "context": {
    "stage": "seed",
    "sector": "fintech",
    "teamSize": "small"
  },
  "reporting": true
}

Set "reporting": false to opt out of anonymous telemetry.

Programmatic API

You can also use Sprinno as a library:

import { runAllScanners } from "@sprinno/scan";

const report = await runAllScanners(process.cwd());
console.log(report.security.secretsWarningCount);
console.log(report.testing.testFileCount);

The Deal: Data Transparency

Sprinno scanning is offline-first , your code never leaves your machine. A pseudonymous identifier tracks your score progress over time. Anonymous calibration metrics (numeric scores only) are sent to improve the scoring model for everyone.

✅ What's Collected (Calibration Data , no identifier)

• Numeric quality scores (0–100) for each pillar and sub-metric
• Programming language and framework identifiers
• Boolean pattern flags (e.g., has_ci: true)
• Repository shape: file count, line count, age in days, contributor count
• Setup context: funding stage, sector, team size
• CLI version and scan timestamp

🚫 What's NEVER Collected

• ❌ Source code , not a single character, line, or token
• ❌ File paths, file names, or directory structure
• ❌ Commit messages, branch names, or tag names
• ❌ Author names, emails, or any PII
• ❌ Repository name, URL, or organizational identity
• ❌ IP addresses (not stored server-side)
• ❌ Code diffs or patches from the fix command

Opting Out

Set "reporting": false in your .sprinnorc file. Scanning, scoring, deltas, and the fix command all work fully offline , you just won't receive cohort percentile comparisons.

Right to Erasure

Run npx @sprinno/scan forget to permanently delete all server-side history.

Full details: TERMS.md | sprinno.xyz/terms

Sprinno Cloud

| Feature | Free | Pulse ($4/mo) | Pro ($49/mo) | |---------|------|---------------|-------------------|\n| Quality scan (5 pillars) | ✅ | ✅ | ✅ | | .sprinno.json output | ✅ | ✅ | ✅ | | Self-comparison deltas | ✅ | ✅ | ✅ | | fix auto-fixable | ✅ | ✅ | ✅ | | SVG score card | ✅ | ✅ | ✅ | | CI/CD quality gate | ✅ | ✅ | ✅ | | Cohort calibration | Monthly | Weekly | Every scan | | fix needs-review | 2/month | Unlimited | Unlimited | | Trend sparkline | - | ✅ | ✅ | | Targeted recommendations | - | ✅ | ✅ | | Score projections | - | ✅ | ✅ | | Live badge URL | - | ✅ | ✅ | | Cloud history | - | 90 days | Unlimited | | Team dashboard | - | - | ✅ |

npx @sprinno/scan connect

Or visit sprinno.xyz to get started.

Requirements

• Node.js ≥ 18.0.0
• Git repository (for git-based metrics)
• Works with any language . TypeScript, JavaScript, Python, Go, Java, Rust, Ruby, etc.
• No build step required , purely static analysis

Install Globally (Optional)

npm install -g @sprinno/scan

# Then use directly:
sprinno
sprinno --ci --fail-below 70
sprinno setup

FAQ

No. Sprinno is 100% static analysis. It reads files and checks patterns , no code execution, no build step, no network calls to your infrastructure.

Yes. Run it from the root or any subdirectory. It scans the directory tree from wherever you invoke it.

Set "reporting": false in .sprinnorc for fully offline operation. For enterprise air-gapped deployments, contact [email protected].

Sprinno is not a replacement for deep SAST tools. It's a holistic quality score across 5 engineering pillars (not just code). It's designed to be instant, zero-config, and context-aware (stage, sector, team size). Think of it as a quick health check, not a detailed medical exam.

The open-source CLI uses hand-tuned weights. Sprinno Cloud uses Latent Capability Scoring (LCS) , calibrated on thousands of anonymized scans , for significantly more accurate scoring. The more people use the CLI, the better LCS gets for everyone.

Contributing

We welcome contributions! Please see the GitHub repository for issues and pull requests.

License

MIT , use it however you want.