CLI Reference

Usage: sawmill [OPTIONS] [LOGFILE]

Flag

Type

Default

Description

LOGFILE

path

Log file to analyze. Opens TUI unless batch flags are present.

--version

flag

Show version and exit.

--list-plugins

flag

List all available plugins and exit.

--plugin

string

Force a specific plugin (bypasses auto-detection).

--show-info

flag

Show detailed info about a plugin. Requires --plugin.

--list-groupings

flag

List available grouping fields from the plugin and exit.

--list-severity

flag

List available severity levels from the plugin and exit.

--severity

string

Filter to show only messages at or above this severity level. See CLI Usage.

--filter

string

Regex pattern to include matching messages.

--suppress

string

Regex pattern to exclude matching messages. Repeatable. See CLI Usage.

--suppress-id

string

Message ID to exclude. Repeatable.

--format

choice

text

Output format: text (coloured), json (JSONL), or count (summary).

--id

string

Message ID pattern to include (supports wildcards, e.g. Synth 8-*). Repeatable.

--category

string

Category to include (from plugin pre-defined filters). Repeatable.

--generate-waivers

flag

Generate waiver TOML from log messages. Output to stdout. See Waivers.

--waiver-level

int

1

Minimum severity level for waiver generation.

--check

flag

Check mode: exit 1 if unwaived messages above threshold. See CI Integration.

--fail-on

string

With --check, set min failure severity. Default: second-lowest from plugin.

--waivers

path

Path to waiver TOML file. See Waivers.

--show-waived

flag

Display messages that were waived (with waiver reasons).

--report-unused

flag

Report waivers that didn’t match any messages (stale waivers).

--report

path

Write JSON summary report to this file. See CI Integration.

--summary

flag

Show summary counts by severity and message ID.

--group-by

choice

Group output by field: severity, id, file, or category.

--top

int

5

Limit messages shown per group with --group-by. 0 = no limit.

--batch

flag

Force batch mode (no TUI). Implied by any output/filter/check flag.

-h / --help

flag

Show help and exit.

Batch mode detection

Sawmill runs in batch mode (no TUI) when any of these conditions are true:

  • --batch is passed.

  • Any filter, output, or check flag is present (--severity, --filter, --suppress, --id, --category, --format explicitly set, --check, --fail-on, --waivers, --show-waived, --report-unused, --report, --summary, --group-by, --generate-waivers).

  • Standard input is not a TTY (piped input, CliRunner, etc.).