CLI Usage¶

Basic usage¶

Run sawmill with a log file:

$ sawmill build.log

With no extra flags, sawmill opens the TUI. Add --batch (or any output/filter/check flag) to run in batch mode:

$ sawmill build.log --batch

Sawmill auto-detects the appropriate plugin by asking each installed plugin how confident it is about the file. To override auto-detection:

$ sawmill build.log --plugin vivado

List installed plugins:

$ sawmill --list-plugins

Show detailed information about a plugin, including its filters and severity levels:

$ sawmill --show-info --plugin vivado

Output formats¶

Sawmill supports three output formats:

--format text (default): Coloured, human-readable output. Each message is printed with its severity style applied.
--format json: JSONL (one JSON object per line). Each object contains start_line, end_line, raw_text, content, severity, message_id, category, and optionally file_ref.
--format count: A single-line summary: total=N error=N warning=N ...

Example:

$ sawmill build.log --format json | jq '.severity'

Filtering¶

By severity — show messages at or above a severity level:

$ sawmill build.log --severity warning

The valid severity names come from the plugin. Use --list-severity --plugin <name> to see them.

By regex — include only messages matching a pattern:

$ sawmill build.log --filter "timing.*slack"

By message ID — include messages with matching IDs. Supports glob-style wildcards:

$ sawmill build.log --id "Synth 8-*"
$ sawmill build.log --id "Vivado 12-3523" --id "DRC *"

By category — include messages in a given category (defined by the plugin’s pre-defined filters):

$ sawmill build.log --category timing --category drc

Suppressing display noise¶

Suppressions hide messages from output. They have no effect on CI pass/fail (see CI Integration).

By regex pattern:

$ sawmill build.log --suppress "INFO:.*Synthesizing"

By message ID:

$ sawmill build.log --suppress-id "Vivado 12-1023"

Both options can be repeated. If --suppress or --suppress-id is combined with --check, sawmill emits a stderr warning reminding you that suppressions are display-only.

Grouping and summary¶

Summary mode shows counts by severity and message ID, similar to hal_log_parser.py:

$ sawmill build.log --summary

Group-by mode groups messages by a field and shows sample messages per group:

$ sawmill build.log --group-by severity
$ sawmill build.log --group-by id --top 3
$ sawmill build.log --group-by file
$ sawmill build.log --group-by category

--top N limits the number of sample messages shown per group (default: 5, --top 0 for no limit).

List available grouping fields (including plugin-specific ones):

$ sawmill --list-groupings --plugin vivado

Waiver generation¶

Generate a waiver TOML file from errors and warnings in a log:

$ sawmill build.log --generate-waivers > waivers.toml

By default, messages at severity level 1 and above are included. Adjust the threshold with --waiver-level:

$ sawmill build.log --generate-waivers --waiver-level 0

The generated file contains placeholder values for reason and author that you should review and update before committing.

See Waivers for the waiver file format.