CLI and output reference
Command line
Section titled “Command line”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 option | Meaning |
|---|---|
-h, --help | Print help |
-V, --version | Print 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.
Commands
Section titled “Commands”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 option | Meaning |
|---|---|
--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 |
--quiet | Suppress non-essential output |
--write | Create the configuration file instead of only previewing it |
-h, --help | Print help |
The starter configuration sets only schema_version, so every supported language uses the
built-in defaults. --write fails if the file already exists.
languages
Section titled “languages”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 option | Meaning |
|---|---|
--root <ROOT> | Repository root scanned by --detected. Defaults to the current directory |
--format <FORMAT> | Output format. Defaults to humanAllowed values:
|
--detected | List languages detected under the root instead of every supported language |
-h, --help | Print help (see a summary with '-h') |
check [PATHS]...
Section titled “check [PATHS]...”Checks the whole repository when no paths are given, or only the selected paths.
Usage: sprawl-guard check [OPTIONS] [PATHS]...
| Argument or option | Meaning |
|---|---|
--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 |
--quiet | Suppress non-essential output |
--format <FORMAT> | Output format. Defaults to [output].format in the configuration, or humanAllowed values:
|
--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-current | Fail when the ratchet file has stale entries. This is the default Conflicts with: --no-require-ratchet-current |
--no-require-ratchet-current | Allow 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 failAllowed values:
|
[PATHS]... | Paths to check. Checks the whole repository when omitted |
-h, --help | Print 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.
update [PATHS]...
Section titled “update [PATHS]...”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 option | Meaning |
|---|---|
--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 |
--quiet | Suppress non-essential output |
--write | Save the ratchet changes instead of only previewing them |
--allow-increases | Raise 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-linesAllowed values:
|
--format <FORMAT> | Output format Default: humanAllowed values:
|
[PATHS]... | Paths to scan for new violations. Scans the whole repository when omitted |
-h, --help | Print 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.
A comment before the first line of code disables max-lines or every rule, as in
/* oxlint-disable max-lines */ or /* oxlint-disable */. eslint-disable comments also count
when Oxlint is installed, unless the Oxlint configuration sets
options.respectEslintDisableDirectives to false. Comments don’t exempt a file that contains
oxlint-enable or eslint-enable anywhere.
tighten [PATHS]...
Section titled “tighten [PATHS]...”Lowers existing ratchet ceilings after violations improve. It never creates or raises ceilings.
Usage: sprawl-guard tighten [OPTIONS] [PATHS]...
| Argument or option | Meaning |
|---|---|
--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 |
--quiet | Suppress non-essential output |
--write | Save the ratchet changes instead of only previewing them |
--format <FORMAT> | Output format Default: humanAllowed values:
|
[PATHS]... | Paths whose ratchet entries are evaluated. Evaluates the whole ratchet file when omitted |
-h, --help | Print 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.
Inspect and upgrade configuration
Section titled “Inspect and upgrade configuration”Besides config import, the config command has these subcommands:
config resolvedprints 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_lineslists every counted line type, includingcode.[files].excludelists the built-in and added excludes together.- A language with an explicit
includelists its added globs there.
config exportprints the complete configuration, ready to commit. It uses the same keys and values as a hand-written file, socount_lines = []means only code lines count.config upgradepreviews the configuration upgraded to the current schema.--writesaves it, and--checksaves nothing and exits1when an upgrade is pending.
To list only the languages found in the repository, use languages --detected.
pnpm exec sprawl-guard config upgrade --checknpm exec -- @kpozin/sprawl-guard config upgrade --checkuv run sprawl-guard config upgrade --checksprawl-guard config upgrade --checksprawl-guard config upgrade --checkpnpm exec sprawl-guard config resolvedpnpm exec sprawl-guard languages --detectednpm exec -- @kpozin/sprawl-guard config resolvednpm exec -- @kpozin/sprawl-guard languages --detecteduv run sprawl-guard config resolveduv run sprawl-guard languages --detectedsprawl-guard config resolvedsprawl-guard languages --detectedsprawl-guard config resolvedsprawl-guard languages --detectedUsage: sprawl-guard config resolved [OPTIONS]
| Argument or option | Meaning |
|---|---|
--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, --help | Print help |
Usage: sprawl-guard config export [OPTIONS]
| Argument or option | Meaning |
|---|---|
--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, --help | Print help |
Usage: sprawl-guard config upgrade [OPTIONS]
| Argument or option | Meaning |
|---|---|
--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 |
--quiet | Suppress non-essential output |
--write | Save the upgraded configuration instead of only previewing it Conflicts with: --check |
--check | Save nothing, and exit with code 1 when an upgrade is pending |
-h, --help | Print help |
config import {eslint|oxlint}
Section titled “config import {eslint|oxlint}”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
maxsets the limit. Withoutmax, the limit is the linter’s default of 300 lines. count_linesincludes comments unless the rule setsskipComments: true, and blank lines unless it setsskipBlankLines: true.- The import fails if the rule is off or missing.
Usage: sprawl-guard config import [OPTIONS] <COMMAND>
| Argument or option | Meaning |
|---|---|
--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 |
--write | Save the configuration instead of only previewing it. Fails if the configuration file already exists |
-h, --help | Print 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 option | Meaning |
|---|---|
<FILE> | Source file, relative to the root, whose ESLint configuration to read |
-h, --help | Print help |
config import oxlint reads the Oxlint configuration that applies at the root. It ignores the
configuration’s overrides, so use Sprawl Guard
path overrides for per-path limits. Oxlint
can omit inherited options when it prints the
configuration, so compare the imported limit with any configuration that yours extends.
Usage: sprawl-guard config import oxlint
| Argument or option | Meaning |
|---|---|
-h, --help | Print help |
schema {config|ratchet}
Section titled “schema {config|ratchet}”Prints the selected JSON Schema for local or offline editor integration.
Usage: sprawl-guard schema <DOCUMENT>
| Argument or option | Meaning |
|---|---|
<DOCUMENT> | TOML document kind whose JSON Schema to print Allowed values:
|
-h, --help | Print help (see a summary with '-h') |
explain PATH
Section titled “explain PATH”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 bystored in Git LFS. JSON reports them asfile_bytes, with the file’sstorage(regularorlfs), thelimitthat applies to that storage, and asizewhosestateismeasuredornot_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 ofstate: "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 inmeasurements. - 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 inunreadable_paths. - A directory that
checkskips, such as a hidden or gitignored one, is reported as ignored. A symlink to a directory counts as a directory when[traversal].follow_symlinksfollows directories. - The config file and the ratchet file are never source files.
explainreports them asconfig_excludedandratchet_excluded.
Usage: sprawl-guard explain [OPTIONS] <PATH>
| Argument or option | Meaning |
|---|---|
--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 humanAllowed values:
|
<PATH> | File or directory to explain. A file path does not need to exist |
-h, --help | Print help (see a summary with '-h') |
Output formats
Section titled “Output formats”- 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 likesrc/big.rs: 700 lines (limit 400), orsrc/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 asShowing 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 withcheck --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
toolExecutionNotificationsof the run’s invocation, at levelerrororwarning, andexecutionSuccessfulisfalsewhen they fail the check. - GitHub output prints the human report, then one GitHub Actions annotation for each violation and
gap the report lists:
::errorfor violations and for gaps that fail the check,::warningfor 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 whenGITHUB_WORKSPACEnames 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.
- The human report sits between
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,failedwhen there are violations, orerrorwhen 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, orpartialwith theunreadable_pathsbelow the root and theuncounted_filestoo 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.warningsandviolations: structured diagnostics. Each violation’skindisfile_lines,test_file_lines,file_bytes,lfs_object_bytes,directory_direct_files, ortest_directory_direct_files, or, for a stale ratchet entry, one of these kinds followed by_stale. A file or directory violation’sratchetfield holds its ratchet ceiling when it grew above one, and isnullwhen the ratchet file has no entry for it. Anlfs_object_bytesviolation is for a Git LFS file, and afile_bytesviolation is for any other file. Each warning has akindand apath. Arust_cfg_test_parse_failedwarning adds the parser’sdetail. Anlfs_pointer_sourcewarning, for a source file whose lines weren’t counted because it is a Git LFS pointer, adds the file’sroleand thedeclared_bytesof the object. Aselected_path_skippedwarning 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.
pnpm exec sprawl-guard check --format sarifnpm exec -- @kpozin/sprawl-guard check --format sarifuv run sprawl-guard check --format sarifsprawl-guard check --format sarifsprawl-guard check --format sarifSARIF rule IDs
Section titled “SARIF rule IDs”| 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.
Exit codes
Section titled “Exit codes”Check the exit code before you parse JSON or SARIF output:
pnpm exec sprawl-guard check --format jsonnpm exec -- @kpozin/sprawl-guard check --format jsonuv run sprawl-guard check --format jsonsprawl-guard check --format jsonsprawl-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.