CLI Reference

fast-classifier [global options] <command>

Global options

Accepted before or after the subcommand — both fast-classifier --execute sweep and fast-classifier sweep --execute parse.

Flag	Meaning
-c, --config <path>	path to fast-classifier.config.{ts,mjs,js,json}
-p, --provider <type>	mail transport: jmap or mcp (default: from config)
--execute	apply changes — mutating commands are dry-run by default
--max <n>	cap on emails scanned per run (a positive integer)
--yes	skip confirmation prompts for large mutation batches
--json	print the full report JSON to stdout instead of a summary
--csv	print the report as CSV instead of a summary (array field auto-picked)
--csv-field <path>	dot-path to the array field to flatten, e.g. domains
--view	render the report as a table via tennis instead of printing
--report-dir <dir>	directory for reports and audit logs (default ./.fast-classifier)

Commands

Command	Description
analyze	read-only recon: who fills the inbox, by sender and root domain
plan	classify without touching anything: coverage + unmatched senders
suggest [dir] [--interactive] [--no-interactive] [--write]	read-only scan: suggest config rules for your senders from the built-in domain catalog, plus a paste-ready config fragment
sweep	label + archive bulk mail (keep-list wins; dry-run by default); audits to sweep.log.tsv
file	file classified mail into per-category labels (dry-run by default); audits to file.log.tsv
needs-action [--apply]	score the recent window for mail needing a human response; --apply tags candidates with the needs-action label (never archives) — tagging requires --apply and --execute
labels list	list labels with email totals
labels ensure <names...>	create the given labels if missing, nested as 'Parent/Child' (dry-run by default)
verify [--contains <addrs...>] [--cleared <addrs...>] [--label <specs...>]	post-run assertions; label specs are 'Name' (exists), 'Name=N' (exactly N), 'Name>=N' (at least N)
init [dir] [--from-inbox]	write a starter fast-classifier.config.ts (refuses to overwrite); --from-inbox scans your inbox and builds the config from suggestions instead
mcp	run the MCP server on stdio — prefer the standalone fast-classifier-mcp bin

suggest in detail

suggest runs the analyze scan (read-only), drops root domains your config already covers, and matches the rest against the built-in catalog of well-known senders in 12 generic categories. Catalog hits become rule suggestions; everything else comes back as an unknown domain, sorted by volume, for you to decide on.

• --interactive — walk the results with prompts: one Y/n gate for the whole catalog batch, then a per-domain walk over the unknowns where you pick a category by number, s (or Enter) skips, and q stops the walk. This is the default on a TTY; --json disables prompting.
• --no-interactive — never prompt; accept every catalog suggestion (unknown domains are only reported).
• --write — write the accepted rules as a fresh fast-classifier.config.ts into the [dir] argument (default .). It never overwrites: with an existing config it prints the paste-ready fragment instead.

Without --write, suggest prints the fragment to paste into your defineConfig — including any category definitions your config is missing. --max caps the scan like everywhere else.

fast-classifier suggest                    # suggestions + unknowns + paste-ready fragment
fast-classifier suggest --no-interactive --write   # accept the catalog, write a fresh config
fast-classifier init --from-inbox          # bootstrap: build the starter config from your inbox

init --from-inbox is the same flow at bootstrap time: instead of the generic starter template it scans your inbox, lets you accept suggestions (prompting on a TTY), and writes the resulting config.

verify in detail

• --contains <addrs...> — senders that must still have inbox mail
• --cleared <addrs...> — senders that must have no inbox mail left
• --label <specs...> — label expectations: 'Inbox/Dev' (exists), 'Inbox/Dev=14' (exactly 14 emails), 'Inbox/Dev>=1' (at least 1)

fast-classifier verify --cleared newsletter@example.com --label 'Inbox/Dev>=1'

Reports and exit codes

Every command writes <command>-report.json (credentials redacted) into the report dir and echoes the path on stderr. Dry runs print a DRY RUN — no changes will be made (pass --execute to apply) banner on stderr before the run.

Exit code 1 on errors, on failed verify checks, and when a sweep/file run is aborted by a declined confirmation (non-interactive runs planning more than 100 mutations refuse the batch unless --yes is passed).