# CLI and output reference

Commands, options, formats, diagnostics, and exit codes.

Commands on this page run `sprawl-guard` as installed with Cargo or Homebrew. If you installed Sprawl Guard with pnpm, npm, or uv, replace `sprawl-guard` with `pnpm exec sprawl-guard`, `npm exec -- @kpozin/sprawl-guard`, or `uv run sprawl-guard`.

## 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

### `init`

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`

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 `human` **Allowed values:** `human` — Human-readable text output; `json` — JSON output |
| `--detected`        | List languages detected under the root instead of every supported language                                        |
| `-h, --help`        | Print help (see a summary with '-h')                                                                              |

### `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 `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-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 `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, --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]...`

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-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, --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:

**ESLint**

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.

**Oxlint**

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]...`

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:** `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, --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

Besides [`config import`](#config-import-eslintoxlint), 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`.

```sh title="Check that the configuration is current"
sprawl-guard config upgrade --check
```

```sh title="Inspect the configuration"
sprawl-guard config resolved
sprawl-guard languages --detected
```

`Usage: 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}`

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 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**

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                                                            |

**Oxlint**

`config import oxlint` reads the Oxlint configuration that applies at the root. It ignores the
configuration's `overrides`, so use Sprawl Guard
[path overrides](/sprawl-guard/reference/configuration.md#overrides) for per-path limits. Oxlint
[can omit inherited options](https://github.com/oxc-project/oxc/issues/22230) 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}`

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:** `config` — Root configuration files; `ratchet` — Ratchet files |
| `-h, --help`       | Print help (see a summary with '-h')                                                                                             |

### `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 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 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 `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, --help`        | Print help (see a summary with '-h')                                                                              |

## 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 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](#sarif-rule-ids). 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:

```json
{
  "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.

```sh title="Check as SARIF"
sprawl-guard check --format sarif
```

### 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

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

```sh title="Check as JSON"
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.
