MailSweep CLI Reference Manual

MailSweep provides a unified command-line interface (mailsweep). You can execute the automated end-to-end pipeline (sweep) or run individual subcommands for specific tasks.

---

1. Automated Workflow (mailsweep sweep)

The sweep command executes the full pipeline in sequence. It scans headers, builds a classification plan, audits safety, creates an offline backup archive, and moves targeted clutter messages to Trash.

# Preview actions in safe Dry-Run mode (default)
mailsweep sweep

# Execute live sweep (verified backup -> non-destructive move to Trash)
mailsweep sweep --execute

# Relocate clutter to custom destination folder
mailsweep sweep --action move --dest "ClutterFolder" --execute

# Specify explicit Trash folder
mailsweep sweep --trash-folder "[Gmail]/Trash" --execute

# Save timestamped backup to custom directory
mailsweep sweep --backup-dir "custom_backups" --execute

# Skip offline backup creation before cleanup
mailsweep sweep --no-backup --execute

# Bypass local cache and re-scan entire mailbox
mailsweep sweep --fresh --execute

# Save intermediate scan and plan JSON files to disk
mailsweep sweep --save-snapshots

Options

Flag	Type	Default	Description
--action	Choice (trash, move, mark_read)	trash	Specify cleanup action for clutter messages.
--dest	String	Archive	Specify destination folder when action is move.
--trash-folder	String	None	Specify destination folder for trash messages (auto-detects server trash by default).
--backup-dir	Path	backups	Specify directory path for offline backup archives.
--no-backup	Flag	False	Skip offline backup archive creation before cleanup.
--no-zip	Flag	False	Store raw .eml files without creating a compressed ZIP archive.
--fresh	Flag	False	Bypass local cache and scan entire mailbox.
--no-cache	Flag	False	Disable reading and writing local metadata cache.
--dry-run	Flag	False	Simulate pipeline operations without modifying mailbox (default).
--execute	Flag	False	Execute live cleanup and archive changes on IMAP mailbox.
--save-snapshots	Flag	False	Save intermediate scan and target JSON files to disk.

---

2. Modular Subcommands

2.1 Scanner (mailsweep scan)

Scan mailbox headers and record immutable IMAP UIDs into scan_summary.json.

• Fetches headers in 100-message BODY.PEEK batches without changing \Seen flags.
• Decodes multi-pass RFC 2047 MIME headers for Subject, From, and To fields.
• Extracts Google X-GM-EXT-1 protocol extensions (X-GM-MSGID, X-GM-LABELS) on Gmail servers.
• Deduplicates messages across virtual folders and discovers Gmail All Mail when category folders are absent.
• Parses unsubscription headers (RFC 8058, RFC 2369) and conversation references (RFC 5322).
• Detects transactional PDF attachments and calendar invites (RFC 5545).
• Updates the incremental local cache in .mailsweep_cache/.

# Scan mailbox using incremental cache
mailsweep scan

# Bypass cache and re-scan all folders
mailsweep scan --fresh

# Disable local cache reading and writing
mailsweep scan --no-cache

Options

Flag	Type	Default	Description
--fresh	Flag	False	Bypass local cache and scan entire mailbox.
--no-cache	Flag	False	Disable reading and writing local metadata cache.

---

2.2 Classification Planner (mailsweep plan)

Generate a multilingual classification cleanup plan from a scan summary file.

• Tier 0 Immunity: Private and workplace domains from IMAP_USER and USER_DOMAINS.
• Tier 1 Immunity: Human conversation threads with verified In-Reply-To or References.
• Tier 2 Immunity: Transactional documents with verified PDF attachments.
• Tier 3 Immunity: Invoices, receipts, subscription renewals, and housing management.
• Tier 4 Immunity: Critical personal, employment, health, tax, and legal records.
• Tier 5 Immunity: Shipping tracking numbers, delivery notices, and calendar invites.
• Targeted Clutter: Surveys, marketing newsletters (RFC bulk and Gmail smart labels), social notifications, and automated alerts.

Safety tiers always evaluate before clutter rules. Gmail promotional or social labels never override safety tiers for receipts, invoices, or critical documents.

# Generate targets_to_delete.json from scan_summary.json
mailsweep plan

# Specify custom input summary and output plan paths
mailsweep plan --summary "my_scan.json" --output "my_plan.json"

Options

Flag	Type	Default	Description
--summary	Path	scan_summary.json	Specify path to input scan summary JSON file.
--output	Path	targets_to_delete.json	Specify path for output targets JSON plan.

---

2.3 Offline Archiver (mailsweep backup)

Download targeted .eml messages and generate a compressed backup archive with SHA-256 integrity verification.

# Download targeted emails to timestamped ZIP archive in backups/
mailsweep backup

# Save backup archive to custom directory
mailsweep backup --output-dir "custom_backups"

# Specify custom plan input file
mailsweep backup --senders-file "my_plan.json"

# Limit download count
mailsweep backup --limit 500

# Save uncompressed .eml files directly in directory
mailsweep backup --no-zip

# Discard partial backup data and start fresh download
mailsweep backup --fresh

Options

Flag	Type	Default	Description
--senders-file	Path	targets_to_delete.json	Specify path to target items JSON file.
--output-dir	Path	backups	Specify directory path for backup archives.
--limit	Integer	0	Limit count of messages to download (0 = all).
--no-zip	Flag	False	Store raw .eml files without creating a compressed ZIP archive.
--fresh	Flag	False	Discard partial backup data and start fresh download.

---

2.4 Non-Destructive Cleaner (mailsweep clean)

Relocate or trash targeted clutter messages according to a cleanup plan.

# Preview cleanup actions in dry-run mode (default)
mailsweep clean

# Execute live cleanup to server Trash folder
mailsweep clean --execute

# Specify explicit Trash folder
mailsweep clean --trash-folder "[Gmail]/Trash" --execute

# Relocate messages to custom archive folder instead of Trash
mailsweep clean --action move --dest "Archive" --execute

# Mark targeted messages as read without moving them
mailsweep clean --action mark_read --execute

# Clean specific senders directly
mailsweep clean --senders "promo@example.com" "news@example.com" --execute

Options

Flag	Type	Default	Description
--senders	List of Strings	None	Specify sender email addresses to target directly.
--senders-file	Path	targets_to_delete.json	Specify path to target items JSON file.
--action	Choice (trash, move, mark_read)	trash	Specify cleanup action for targeted messages.
--dest	String	Archive	Specify destination folder when action is move.
--trash-folder	String	None	Specify destination folder for trash messages (auto-detects server trash by default).
--execute	Flag	False	Execute live cleanup changes on IMAP mailbox.

---

2.5 Mailbox Restorer (mailsweep restore)

Restore messages from an offline backup archive back into their original IMAP folders.

# Search and preview matching messages in backup archive (dry-run default)
mailsweep restore --backup "backups/email_backup_20260821_082715.zip" --query "Invoice"

# Execute live restore by search query
mailsweep restore --backup "backups/email_backup_20260821_082715.zip" --query "Invoice" --execute

# Restore messages by sender email address
mailsweep restore --backup "backups/email_backup_20260821_082715.zip" --sender "billing@example.com" --execute

# Restore messages by exact subject keyword
mailsweep restore --backup "backups/email_backup_20260821_082715.zip" --subject "Monthly Statement" --execute

Options

Flag	Type	Default	Description
--backup	Path	(Required)	Specify path to backup archive file.
--query	String	""	Filter messages by subject or sender keyword.
--sender	String	""	Filter messages by sender email address.
--subject	String	""	Filter messages by subject text.
--execute	Flag	False	Execute live restore to IMAP mailbox.

---

2.6 Brand Unsubscribe Hub (mailsweep unsubscribe)

Consolidate senders by brand identity and generate a local web dashboard (unsubscribe_dashboard.html).

• Groups sub-addresses into unified brand subscription cards.
• Performs parallel HTTP and DNS health checks on unsubscription links.
• Surfaces official preference management portals.

# Generate dashboard with active link health verification
mailsweep unsubscribe

# Generate dashboard quickly without link health verification
mailsweep unsubscribe --skip-check

Options

Flag	Type	Default	Description
--skip-check	Flag	False	Skip HTTP health checks for unsubscription links.

---

2.7 Classification Safety Auditor (mailsweep audit)

Audit classification decisions and backup archives against 13-language European safety heuristics.

1. False-Positive Audit: Verify that no critical personal, legal, or financial emails match the deletion plan.
2. False-Negative Audit: Inspect preserved emails to find remaining promotional clutter.
3. Backup Protection Audit: Inspect offline ZIP archives to verify that zero protected messages were packaged.

# Audit last scan summary (scan_summary.json)
mailsweep audit

# Audit specific scan summary file
mailsweep audit --summary "custom_summary.json"

# Audit an offline backup archive
mailsweep audit --backup "backups/email_backup_20260821_082715.zip"

Options

Flag	Type	Default	Description
--summary	Path	scan_summary.json	Specify path to scan summary JSON file.
--backup	Path	None	Specify path to backup archive file to audit.

---

2.8 Rules Registry & Sync (mailsweep rules)

Validate classification rules, audit 13-language coverage, and synchronize rule definitions from upstream sources.

# Validate syntax and regex integrity of default rules
mailsweep rules --check

# Validate a custom rules JSON file
mailsweep rules --rules "path/to/custom_rules.json" --check

# Display 13-language rule coverage scorecard
mailsweep rules --audit-languages

# Synchronize all feeds defined in sources.json (SpamAssassin, Rspamd, RFCs)
mailsweep rules --sync-sources

# Synchronize feeds from a custom manifest file
mailsweep rules --sync-sources --sources "path/to/sources.json"

# Synchronize rules from a single remote URL endpoint
mailsweep rules --sync-upstream --source "https://example.com/custom_rules.json"

Options

Flag	Type	Default	Description
--rules	Path	rules.json	Specify path to classification rules JSON file.
--check	Flag	False	Validate syntax and regex integrity of classification rules.
--audit-languages	Flag	False	Display 13-language rule coverage scorecard.
--sync-upstream	Flag	False	Synchronize rules from single upstream endpoint.
--source	String	""	Specify custom URL endpoint for rule synchronization.
--sync-sources	Flag	False	Synchronize all rule sources defined in manifest.
--sources	Path	sources.json	Specify path to sources manifest file.

---

2.9 Test Suite Runner (mailsweep test)

Run the automated unit test suite.

# Run full unit test suite
mailsweep test

# Run tests with verbose output
mailsweep test -v

# Run tests with quiet summary output
mailsweep test -q

Options

Flag	Type	Default	Description
-v, --verbose	Flag	False	Display verbose test output with test names.
-q, --quiet	Flag	False	Display quiet test output with error summary only.