Skip to content

CLI and output reference

Write each option after the command it belongs to, as in sprawl-guard check --format json. Run commands from the repository root, or pass its path with --root.

Usage: sprawl-guard <COMMAND>

Argument or optionMeaning
-h, --helpPrint help
-V, --versionPrint version

The npm package includes native builds for macOS (x64 and Arm), Windows (x64), Alpine Linux (x64), and other Linux distributions (x64 and Arm) from Ubuntu 22.04, Debian 12, and Fedora 36 onward. Anywhere else, including older Linux releases, Red Hat Enterprise Linux 9, Rocky Linux 9, AlmaLinux 9, and Amazon Linux 2023, it falls back to a slower WebAssembly build.

Prints a starter configuration for sprawl-guard.toml, or for the file you pass with --config. With --write, init saves the configuration to that file instead.

Usage: sprawl-guard init [OPTIONS]

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
--quietSuppress non-essential output
--writeCreate the configuration file instead of only previewing it
-h, --helpPrint help

The starter configuration sets only schema_version, so every supported language uses the built-in defaults. --write fails if the file already exists.

Lists every supported language, or only the languages detected under the root. Human output is a table of language, key, and extensions. JSON adds bundled filenames, automatic language groups, and automatic count_lines. --format defaults to human.

Usage: sprawl-guard languages [OPTIONS]

Argument or optionMeaning
--root <ROOT>Repository root scanned by --detected. Defaults to the current directory
--format <FORMAT>Output format. Defaults to human
Allowed values:
  • human — Human-readable text output
  • json — JSON output
--detectedList languages detected under the root instead of every supported language
-h, --helpPrint help (see a summary with '-h')

Checks the whole repository when no paths are given, or only the selected paths.

Usage: sprawl-guard check [OPTIONS] [PATHS]...

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
--quietSuppress non-essential output
--format <FORMAT>Output format. Defaults to [output].format in the configuration, or human
Allowed values:
  • human — Human-readable text output
  • json — JSON output
  • sarif — SARIF output
  • github — Human-readable text output, followed by GitHub Actions annotations
--max-findings <N|unlimited>Most findings the human report lists, or unlimited. Group totals and the exit status always cover every finding, and JSON and SARIF output list them all. Defaults to [output].max_findings in the configuration, or 50
--require-ratchet-currentFail when the ratchet file has stale entries. This is the default
Conflicts with: --no-require-ratchet-current
--no-require-ratchet-currentAllow stale ratchet entries, for exploratory local checks
Conflicts with: --require-ratchet-current
--unreadable-paths <UNREADABLE_PATHS>What to do with files or directories that cannot be read. Defaults to [traversal].unreadable_paths in the configuration, or fail
Allowed values:
  • fail — List the unreadable paths found while scanning, then fail
  • warn — Report the unreadable paths found while scanning as warnings, and continue
[PATHS]...Paths to check. Checks the whole repository when omitted
-h, --helpPrint help (see a summary with '-h')

--require-ratchet-current and --no-require-ratchet-current cannot be combined. The check reports every unreadable path and every source file too large to count along with its violations. With --unreadable-paths warn, those gaps are warnings, so a check can pass with a partial report. A selected path that doesn’t exist is still an error. A selected path that the scan skips, because it is hidden or an ignore file excludes it, is not checked. Human and JSON output warn about each one, and SARIF output lists each as a notification. The exit code doesn’t change, so a hook that hides the output of a passing command hides the warning too.

Adds ratchet entries for new violations. By default it previews the added or raised ceilings with their before-and-after values, and --write saves them. Existing ceilings stay unchanged unless you pass --allow-increases. To print the complete resulting ratchet file, including unchanged entries, use --format toml.

Usage: sprawl-guard update [OPTIONS] [PATHS]...

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
--quietSuppress non-essential output
--writeSave the ratchet changes instead of only previewing them
--allow-increasesRaise existing ratchet ceilings to current measurements. Without this flag, update never raises them
--import <LINTER>Add entries only for oversized files that LINTER exempts from max-lines
Allowed values:
  • eslint — ESLint
  • oxlint — Oxlint
--format <FORMAT>Output format
Default: human
Allowed values:
  • human — List the ratchet entries that would be added or raised
  • toml — Print the complete resulting ratchet file as TOML
[PATHS]...Paths to scan for new violations. Scans the whole repository when omitted
-h, --helpPrint help (see a summary with '-h')

With no paths, update covers the whole repository. With paths, it covers only those paths.

With --import eslint or --import oxlint, update adds entries only for oversized files that the linter exempts from max-lines, and none for directories.

A file in any language is exempt when the linter’s bulk suppressions file at the root, eslint-suppressions.json or oxlint-suppressions.json, lists it for max-lines with a count above zero. A JavaScript, JSX, TypeScript, or TSX file is also exempt when it disables the rule itself:

Any directive that ESLint honors counts, because Sprawl Guard runs ESLint on the file. ESLint must be installed in node_modules under the root or one of its parents. If ESLint can’t parse the file, the import fails.

Lowers existing ratchet ceilings after violations improve. It never creates or raises ceilings.

Usage: sprawl-guard tighten [OPTIONS] [PATHS]...

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
--quietSuppress non-essential output
--writeSave the ratchet changes instead of only previewing them
--format <FORMAT>Output format
Default: human
Allowed values:
  • human — List the ratchet entries that would be lowered or removed
  • toml — Print the complete resulting ratchet file as TOML
[PATHS]...Paths whose ratchet entries are evaluated. Evaluates the whole ratchet file when omitted
-h, --helpPrint help (see a summary with '-h')

With no paths, tighten covers every ratchet entry. With paths, it covers only the entries under them. The output lists lowered or removed ceilings, and --format toml prints the complete resulting ratchet file. When no ceiling changes, --write leaves the file untouched.

Besides config import, the config command has these subcommands:

  • config resolved prints the effective settings: the built-in defaults merged with your configuration, including each language’s inherited line limits. It’s for reading, not loading, and spells values out as checks use them:
    • count_lines lists every counted line type, including code.
    • [files].exclude lists the built-in and added excludes together.
    • A language with an explicit include lists its added globs there.
  • config export prints the complete configuration, ready to commit. It uses the same keys and values as a hand-written file, so count_lines = [] means only code lines count.
  • config upgrade previews the configuration upgraded to the current schema. --write saves it, and --check saves nothing and exits 1 when an upgrade is pending.

To list only the languages found in the repository, use languages --detected.

Check that the configuration is current
pnpm exec sprawl-guard config upgrade --check
Inspect the configuration
pnpm exec sprawl-guard config resolved
pnpm exec sprawl-guard languages --detected

Usage: sprawl-guard config resolved [OPTIONS]

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
-h, --helpPrint help

Usage: sprawl-guard config export [OPTIONS]

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
-h, --helpPrint help

Usage: sprawl-guard config upgrade [OPTIONS]

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
--quietSuppress non-essential output
--writeSave the upgraded configuration instead of only previewing it
Conflicts with: --check
--checkSave nothing, and exit with code 1 when an upgrade is pending
-h, --helpPrint help

Prints a configuration that applies the linter’s max-lines limit to production and test files in JavaScript, JSX, TypeScript, and TSX. Other languages keep the built-in limits. The linter must be installed in node_modules under the root or one of its parents.

--write saves the configuration to sprawl-guard.toml or the --config file, and fails if that file exists. Pass --write before the linter name, as in config import --write oxlint.

  • The rule’s max sets the limit. Without max, the limit is the linter’s default of 300 lines.
  • count_lines includes comments unless the rule sets skipComments: true, and blank lines unless it sets skipBlankLines: true.
  • The import fails if the rule is off or missing.

Usage: sprawl-guard config import [OPTIONS] <COMMAND>

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
--writeSave the configuration instead of only previewing it. Fails if the configuration file already exists
-h, --helpPrint help

ESLint can configure each file differently, so config import eslint reads the rule that applies to the source file you name, relative to the root.

Usage: sprawl-guard config import eslint <FILE>

Argument or optionMeaning
<FILE>Source file, relative to the root, whose ESLint configuration to read
-h, --helpPrint help

Prints the selected JSON Schema for local or offline editor integration.

Usage: sprawl-guard schema <DOCUMENT>

Argument or optionMeaning
<DOCUMENT>TOML document kind whose JSON Schema to print
Allowed values:
  • config — Root configuration files
  • ratchet — Ratchet files
-h, --helpPrint help (see a summary with '-h')

Shows, for one path, whether it is ignored or excluded, which language claims it, whether it is a test file, its limits, matching overrides, its current lines, and Rust cfg(test) handling.

  • A file’s size is shown next to its byte limit and the overrides that set that limit, as in size: 1500 bytes (1.5 kB), limit 1000 bytes (1.0 kB). For a file in Git LFS, the size is followed by stored in Git LFS. JSON reports them as file_bytes, with the file’s storage (regular or lfs), the limit that applies to that storage, and a size whose state is measured or not_found.
  • A source file too large to count is reported as not counted, with its size and [traversal].max_parsed_code_file_bytes, instead of failing.
  • A source file that is a Git LFS pointer is reported as not counted. JSON reports "state": "lfs_pointer".
  • A path that doesn’t exist is classified by its name, so you can see where a planned file would land. JSON reports state: "not_found" instead of state: "measured".
  • A directory gets one entry per kind and language group of source files directly inside it, with the files, their count against the limit, any ratchet ceiling, and matching overrides. JSON reports kind: "directory", with the entries in measurements.
  • Unreadable paths under a directory don’t stop explain, even with [traversal].unreadable_paths = "fail". It warns that the counts may be incomplete and lists the paths in unreadable_paths.
  • A directory that check skips, such as a hidden or gitignored one, is reported as ignored. A symlink to a directory counts as a directory when [traversal].follow_symlinks follows directories.
  • The config file and the ratchet file are never source files. explain reports them as config_excluded and ratchet_excluded.

Usage: sprawl-guard explain [OPTIONS] <PATH>

Argument or optionMeaning
--root <ROOT>Repository root. Defaults to the current directory
--config <CONFIG>Configuration file. Relative paths are resolved under --root. Defaults to sprawl-guard.toml under the root
--format <FORMAT>Output format. Defaults to human
Allowed values:
  • human — Human-readable text output
  • json — JSON output
<PATH>File or directory to explain. A file path does not need to exist
-h, --helpPrint help (see a summary with '-h')
  • Human output groups failures under “Files over the line limit”, “Test files over the line limit”, “Files over the byte limit”, “Directories with too many direct files”, “Test directories with too many direct files”, and “Stale ratchet entries”. Gaps in the analysis follow under “Skipped unreadable paths” and “Files too large to count lines”. Each heading shows the group’s total, as in Files over the line limit (3):. Each failure reads like src/big.rs: 700 lines (limit 400), or src/big.rs: 700 lines (limit 400, ceiling 650) when the file grew above its ratchet ceiling. Paths are relative to the root and never quoted; control characters in them are escaped.
  • Human output lists at most 50 findings: gaps that fail the check first, then violations, then warnings, then gaps that are only warnings, so a failing check always shows why it failed. A group cut short ends with … and N more, and a footer such as Showing 50 of 1312 findings. names --max-findings unlimited. A directory with too many direct files names at most that many of them. Set the cap with check --max-findings <N|unlimited> or [output].max_findings; the flag takes precedence.
  • JSON output is a structured report with the root, selected paths, where the configuration came from, the line counter, coverage, warnings, and violations.
  • SARIF output follows SARIF 2.1.0. Violations are results. Gaps in the analysis are toolExecutionNotifications of the run’s invocation, at level error or warning, and executionSuccessful is false when they fail the check.
  • GitHub output prints the human report, then one GitHub Actions annotation for each violation and gap the report lists: ::error for violations and for gaps that fail the check, ::warning for the other gaps.
    • The human report sits between ::stop-commands:: and its resume line, so that file names in it can’t act as workflow commands.
    • Each violation’s annotation title is its SARIF rule ID. Gap annotations have the title sprawl-guard/incomplete-analysis, and those for files too large to count point at the file.
    • File violations point at line 1 of the file. In GitHub Actions, the file’s path is relative to GITHUB_WORKSPACE; otherwise it’s relative to the root. A pull request’s diff shows the annotation only when line 1 is part of the diff.
    • Directory violations, stale ratchet entries, and file violations under a root outside GITHUB_WORKSPACE, or when GITHUB_WORKSPACE names a directory that does not exist, name no file, so GitHub lists them only on the workflow run.
    • GitHub shows at most 10 error annotations per step and 50 per job; the full report stays in the step log.

Human check output starts with Configuration: PATH, or with Configuration: built-in defaults (no sprawl-guard.toml in ROOT) when there is no config file. With --quiet, a passing check prints nothing, and a failing check leaves out warnings and gaps that are only warnings.

check takes its default format from [output].format, and check --format overrides it. Other commands ignore [output].format and default to human. update and tighten also support toml, and languages and explain also support json.

A JSON report with one file violation looks like:

{
"status": "failed",
"root": "/repo",
"paths": "all",
"config_source": {
"kind": "authored",
"path": "/repo/sprawl-guard.toml"
},
"counter": {
"backend": "tokei",
"version": "15.0.0"
},
"coverage": {
"kind": "complete"
},
"summary": {
"files_checked": 12,
"directories_checked": 4,
"languages_detected": 2,
"ratchet_entries": 0
},
"warnings": [],
"violations": [
{
"kind": "file_lines",
"path": "src/large.py",
"language": "Python",
"count_lines": [],
"line_counts": {
"code": 430,
"comments": 18,
"blank_lines": 62
},
"actual": 430,
"limit": 400,
"ratchet": null
}
]
}

The report fields are:

  • status: passed, failed when there are violations, or error when gaps in the analysis fail the check under [traversal].unreadable_paths = "fail".
  • paths: "all" for the whole repository, including a root path such as .; otherwise a list of normalized selected paths.
  • config_source: the config file used, or that only built-in defaults were used.
  • counter: the line counter.
  • coverage: complete, or partial with the unreadable_paths below the root and the uncounted_files too large to count, each with its size and the limit.
  • summary: the number of source files, distinct source directories, and languages checked, plus the number of remaining ratchet entries. Passing human output shows the same summary.
  • warnings and violations: structured diagnostics. Each violation’s kind is file_lines, test_file_lines, file_bytes, lfs_object_bytes, directory_direct_files, or test_directory_direct_files, or, for a stale ratchet entry, one of these kinds followed by _stale. A file or directory violation’s ratchet field holds its ratchet ceiling when it grew above one, and is null when the ratchet file has no entry for it. An lfs_object_bytes violation is for a Git LFS file, and a file_bytes violation is for any other file. Each warning has a kind and a path. A rust_cfg_test_parse_failed warning adds the parser’s detail. An lfs_pointer_source warning, for a source file whose lines weren’t counted because it is a Git LFS pointer, adds the file’s role and the declared_bytes of the object. A selected_path_skipped warning names a path given on the command line that the scan skipped because the path is hidden or an ignore file excludes it.

When a path can’t be read or a source file is too large to count, every format still prints the full report. Other errors print only a message on stderr, so check the exit code before parsing stdout.

Check as SARIF
pnpm exec sprawl-guard check --format sarif
Rule ID Finding
sprawl-guard/file-lines A source file has more lines than its limit.
sprawl-guard/test-file-lines A test file has more lines than its limit.
sprawl-guard/file-bytes A file is larger than its byte limit.
sprawl-guard/directory-direct-files A directory directly contains more source files than its limit.
sprawl-guard/test-directory-direct-files A directory directly contains more test files than its limit.
sprawl-guard/ratchet-stale A ratchet entry’s violation shrank or disappeared.

Configuration, path, I/O, and parsing problems are errors, not violations. Gaps in the analysis aren’t violations either; SARIF output reports them as notifications.

Check the exit code before you parse JSON or SARIF output:

Check as JSON
pnpm exec sprawl-guard check --format json
Code Meaning
0 The command succeeded. For a check, it found no violations.
1 A check found violations, or config upgrade --check found a pending upgrade.
2 A check had gaps that fail it, or an error in configuration, arguments, paths, I/O, parsing, or internal processing.

The npm package uses the same exit codes. If it can’t start Sprawl Guard, it exits 2 with a message on stderr.

© 2026 Konstantin Pozin