Skip to content

Get started

Add Sprawl Guard to a Node.js project (Node.js 22 or newer) or a Python project, or install the command-line tool with Cargo or Homebrew:

Terminal window
pnpm add --save-dev @kpozin/sprawl-guard

Command examples on this site have a pnpm tab. For a command written in the text, such as sprawl-guard check, type pnpm exec sprawl-guard in place of sprawl-guard.

To confirm that what you installed came from the Sprawl Guard release workflow, follow Verify a release.

Run these commands from the repository root.

  1. Create the configuration file, sprawl-guard.toml.

    Initialize a repository
    pnpm exec sprawl-guard init
    pnpm exec sprawl-guard init --write

    The first command shows the file, and the second writes it. Until you add settings to it, Sprawl Guard uses its built-in limits: 400 lines per file (800 for test files) and 10 source files directly inside each directory. To change them, see Configure checks. If the project already uses an ESLint or Oxlint max-lines rule, you can start from that rule instead.

  2. Run the check.

    Run the first check
    pnpm exec sprawl-guard check

    A passing check prints:

    Configuration: sprawl-guard.toml
    No sprawl-guard violations found.
    Checked 2 source files in 2 directories across 2 languages.

    A failing check names each file or directory over its limit:

    Configuration: sprawl-guard.toml
    Files over the line limit (1):
    src/large.py: 430 lines (limit 400)
    language: Python, counting code

If the check passes, commit sprawl-guard.toml and add the check to CI.

An existing repository usually has files and directories over the limits. Instead of fixing them all before you can start, record them in a ratchet file, sprawl-guard.ratchet.toml. The check then allows each recorded violation at its current size. It fails if a recorded violation grows, and also if it shrinks, until you record the smaller size.

  1. Preview the violations to record.

    Terminal window
    pnpm exec sprawl-guard update
    Ratchet changes:
    + add src/large.py (production lines): none -> 430
    + add src/flat (production direct files, group: source): none -> 12
    Preview only; use --write to apply.

    A directory entry also names the language group whose files it counts, as How checks work explains.

    If the list includes generated or third-party code, exclude those paths in the configuration and preview again.

  2. Write the ratchet file and run the check.

    Terminal window
    pnpm exec sprawl-guard update --write
    pnpm exec sprawl-guard check
    Configuration: sprawl-guard.toml
    No sprawl-guard violations found.
    Checked 14 source files in 2 directories across 1 language.
    Passed with 2 ratchet entries remaining.
  3. Commit sprawl-guard.toml and sprawl-guard.ratchet.toml together.

Next, add the check to CI, then read Work with the ratchet to see how to record improvements.

If the project already limits file length with the ESLint or Oxlint max-lines rule, you can import the rule’s limit and the files it exempts. Sprawl Guard runs the project’s own linter with Node.js, so install the linter in node_modules first. Sprawl Guard is tested with ESLint 8.57 and 10, and with Oxlint 1.93.

If sprawl-guard.toml already exists, config import --write fails in step 1. Copy the printed [languages] tables into the file instead.

  1. Preview a configuration based on the rule, then save it. ESLint can configure each file differently, so name a source file whose limit you want:

    Terminal window
    pnpm exec sprawl-guard config import eslint src/index.js
    pnpm exec sprawl-guard config import --write eslint src/index.js
  2. Preview ratchet entries for the oversized files that ESLint exempts, then save them:

    Terminal window
    pnpm exec sprawl-guard update --import eslint
    pnpm exec sprawl-guard update --import eslint --write
  1. Run sprawl-guard check, and compare its results with the linter’s. The two tools count lines slightly differently. The check also applies limits that the linter doesn’t: the number of files directly inside each directory, and the length of files in other languages.

  2. Preview the remaining violations with sprawl-guard update, and fix any that you don’t want to accept. Then record the rest with sprawl-guard update --write.

  3. Remove the max-lines rule from the linter’s configuration, then commit that change together with sprawl-guard.toml and sprawl-guard.ratchet.toml.

The CLI reference explains how Sprawl Guard reads the rule and which exemptions it imports.

© 2026 Konstantin Pozin