.TH check-sieve 1 "10 Apr 2026" "version 1.0.1"
.
.
.
.SH NAME
.
check-sieve - Syntax checker for mail sieves.
.
.SH SYNOPSIS
.
.B check-sieve [options]
.I file
.B [
.I file ...
.B ]
.br
.B check-sieve --help
.br
.B check-sieve --version
.
.SH DESCRIPTION
.
.B check-sieve
is a simple syntax checker for server-side mail sieves. It supports many
mail-sieve RFCs, details of which can be found below.
.
.SH OPTIONS
.
.IP "-h, --help"
Show the program help
.IP "--max-list-length N"
Check length of string lists, and flag any that are longer than the specified length
.IP "--server <host>:<port>"
Connect to the specified server, and only enable advertised capabilities
.IP "--trace-parser"
Trace the operation of the parser
.IP "--trace-scanner"
Trace the operation of the scanner
.IP "--trace-tree"
Trace the abstract-syntax-tree
.IP "--simulate <email-file>"
Simulate sieve processing against an email file (.eml format).
See
.B SIMULATION
below.
.IP "--test-dir <dir>"
Run simulation for every .eml file in
.I dir
and diff each result against a matching .out file.
See
.B SIMULATION
below.
.IP "--rebase <dir>"
Regenerate the .out files in
.I dir
from current simulation output.
See
.B SIMULATION
below.
.IP "--version"
Print out version information
.
.SH SIMULATION
.
.B check-sieve
can simulate how a sieve script sorts mail, making it straightforward to verify
script behavior without deploying to a mail server.
.SS Single-message simulation
.IP "--simulate <email-file>"
.
Validates the sieve script and then evaluates it against the given .eml file.
Each test that matches is printed as
.BR "MATCH: " <test>
and each executed action as
.BR "ACTION: " <action> .
If no delivery action is taken,
.B keep (implicit)
is added automatically per RFC 5228 §4.2.
.br
.B NOTE:
Many RFC extensions are still in progress. Filing an issue for unsupported
extensions will help prioritize what to work on next.
.SS Batch testing with a test directory
A test directory contains .eml files and, optionally, .out files that record
expected simulation output. The .out file for a given email is named after the
email's stem (e.g.\&
.I msg.eml
→
.IR msg.out ).
.IP "--test-dir <dir>"
Runs simulation against every .eml file in
.IR dir .
For each email that has a matching .out file, the actual output (with the
environment-specific first line stripped) is diffed against it. If all
comparisons pass the program exits 0 with no output. If any differ, each diff
is printed followed by a summary on stderr and the program exits 1. Emails
without a .out file are simulated but not compared.
.IP "--rebase <dir>"
Regenerates the .out file for every .eml file in
.IR dir ,
creating or overwriting as needed. Run this after making intentional changes to
a sieve script or the simulator to update the expected output before re-running
.BR --test-dir .
.
.SH BUGS
.
For information on existing issues, and to file a bug report check the following URL:
https://github.com/dburkart/check-sieve/issues
.
.SH AUTHORS
.
Dana Burkart
.br
Stuart Montgomery
.
.SH SUPPORTED RFCs
.
The full list of supported RFCs is:

.RS
Sieve: An Email Filtering Language (RFC 5228)
.br
Variables Extension (RFC 5229)
.br
Date and Index Extensions (RFC 5260)
.br
Vacation Extension (RFC 5230)
.br
Vacation "Seconds" Parameter (RFC 6131)
.br
Include Extension (RFC 6609)
.br
Copying Without Side Effects (RFC 3894)
.br
Reject and Extended Reject Extensions (RFC 5429)
.br
Body Extension (RFC 5173)
.br
Relational Extension (RFC 5231)
.br
MIME Part Tests, Iteration, Extraction, Replacement, and Enclosure (RFC 5703)
.br
Imap4flags Extension (RFC 5232)
.br
Editheader Extension (RFC 5293)
.br
Regex Extension (DRAFT)
.br
Spamtest and Virustest Extensions (RFC 5235)
.br
Extensions for Notifications (RFC 5435)
.br
Subaddress Extension (RFC 5233)
.br
Ihave Extension (RFC 5463)
.br
Environment Extension (RFC 5183)
.br
Sieve Notification Mechanism: mailto (RFC 5436)
.br
Internet Message Access Protocol (IMAP) Events (RFC 6785)
.br
Converting Messages before Delivery (RFC 6558)
.br
Detecting Duplicate Deliveries (RFC 7352)
.br
Externally Stored Lists (RFC 6134)
.br
Delivering to Special-Use Mailboxes (RFC 8579)
.br
File Carbon Copy (FCC) (RFC 8580)
.br
Delivery by MAILBOXID (RFC 9042)
.br
Delivery Status Notifications and Deliver-By Extensions (RFC 6009)
.br
Extension for Processing Calendar Attachments (RFC 9671)
.br
Proton Expiration Extension (vendor-specific)
.br
Proton Eval Extension (vendor-specific)
.br
Dovecot Invoking External Programs (vendor-specific)
.RE