CLI

Scope

This page is the flag contract for the mailwoman command-line interface. Each table is generated from the command's own schema, and each description is that flag's help text verbatim, so this page and mailwoman <command> --help cannot disagree.

The CLI carries 134 commands. This page documents the 20 that a consumer of the published package runs. The rest build the datasets and train the modelsneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' inside a checkout of the repository, and they are listed by group under Commands this page does not cover.

Three conventions apply to every table below.

• A flag written --no-<name> is on by default. Pass it to turn the behavior off.
• A default shown as environment-dependent resolves from the environment at run time. The flag's description names the variable it reads.
• A value in angle brackets in a synopsis is required. A value in square brackets is optional.

Commands are shown here, not run. For executed invocations with their real output, follow the tutorials and how-to guides linked under See also.

Top-level commands

mailwoman autocomplete

mailwoman autocomplete [options] <prefix...>

Argument	Required	Description
<prefix...>	Yes	Prefix string to complete

Flag	Type	Default	Description
--limit [limit]	number	10	Maximum number of completions to return (default 10)
--fst [fst]	string	—	Path to the FSTFST (finite-state transducer). A compact automaton that reads an input sequence and emits an output sequence. Mailwoman encodes gazetteer names and street affixes as FSTs for fast prefix matching and prior injection without search overhead. binary (fstFST (finite-state transducer). A compact automaton that reads an input sequence and emits an output sequence. Mailwoman encodes gazetteer names and street affixes as FSTs for fast prefix matching and prior injection without search overhead.-en-US.bin). Defaults to $MAILWOMAN_FST_BIN or /tmp/v440-stagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone)./en-us/v4.4.0/fstFST (finite-state transducer). A compact automaton that reads an input sequence and emits an output sequence. Mailwoman encodes gazetteer names and street affixes as FSTs for fast prefix matching and prior injection without search overhead.-en-US.bin.
--json	boolean	false	Emit results as a JSON array instead of formattedinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. text

mailwoman doctor

mailwoman doctor [options]

Flag	Type	Default	Description
--json	boolean	false	Emit the report as JSON instead of a checklist: { checks: [{ id, labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag., status, detail, fix?, core }], exitCode } — a superset of { id, status, detail, fix? } (labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. + core aid machine consumers).

mailwoman geocode

mailwoman geocode [options] <address...>

Argument	Required	Description
<address...>	Yes	A formattedinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. postal address to geocode

Flag	Type	Default	Description
--locale [locale]	string	en-US	LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. tag matching a weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. package (en-US, fr-FR). Default en-US.
--bias [bias]	string	—	Proximity-bias points, strongest first: 'lat,lon[:weight];lat,lon' (e.g. the map viewport center, then the user's location). Soft re-rank only — an ambiguous bare postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. follows the nearest hint.
--default-country [default-country]	string	—	ISO-3166 countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. to scope the WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.. Defaults from --localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.'s regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. subtag (en-US → US). Pass 'none' to disable the countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. filter.
--country-scope [country-scope]	auto | locale | none	auto	Whether the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-inferred countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. scopes the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.: 'localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.' always, 'none' never, 'auto' (default) only on the FTS backend. Pin 'localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.' or 'none' to hold countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. policy fixed while changing backends. An explicit --default-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. outranks all three.
--resolve-db [resolve-db]	string	—	Path to a WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. admin SQLite distribution. Defaults to $MAILWOMAN_WOF_DB; errors if neither is set.
--candidate-db [candidate-db]	string	—	Path to a byte-range candidate.db (build-candidate.ts) — the SAME gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. + population-first ranking the browser demo uses. When set (or via $MAILWOMAN_CANDIDATE_DB), the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. matches the demo (e.g. bare 'Moscow' → Russia, not a US township) and --resolve-db is not required.
--data-root [data-root]	string	environment-dependent	Root directory for per-state address-point and interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.. ShardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. are expected at <dataRoot>/address-points/address-points-us-<state>.db and <dataRoot>/interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable./interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable.-us-<state>.db. Defaults to $MAILWOMAN_DATA_ROOT.
--address-points-db [address-points-db]	string	—	Explicit path to an address-points (situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge.) SQLite shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.. Bypasses the per-state shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. selection from the resolved regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.. Use when you already know the right shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. or are testing a specific file.
--interpolation-db [interpolation-db]	string	—	Explicit path to an interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. SQLite shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.. Bypasses the per-state shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. selection. Use when you already know the right shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. or are testing a specific file.
--interp-calibration [interp-calibration]	number	—	Conformal calibrationconformal calibrationA calibration method that adjusts per-prediction uncertainty so a target coverage (e.g. 90%) is guaranteed on held-out data, without retraining the model. multiplier for the interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. tier's reported uncertainty_m (#374). The raw half-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. radius covers only ~72% of true errors. Default (unset): the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.'s own baked value (its interp_calibration metadata table) when it carries one, else the in-code per-regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. table (#584) selected by parsed regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. — 1.44 (DC) … 3.12 (AZ), 1.95 for unmeasured states — for a ~90% bound. Pass an explicit number to force a single multiplier everywhere (1 = raw).
--no-place-country	boolean	true	The #244 coarse-placercoarse-placerA lightweight int8 country classifier (~0.79 MB) that predicts which of a set of target countries an address belongs to, feeding a soft prior into resolver disambiguation. soft countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. prior (open-set rule). A confident whole-string countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. guess biases the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.'s localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy./regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. ranking toward the right countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. (never filters); most useful when no --default-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. / localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. pins it. ON by default after the M2 misroute gate (0 misroutes); pass --no-place-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. to disable.
--no-postcode-country-coherence	boolean	true	#42: let a (postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one., localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.) pair that is geographically consistent in exactly ONE countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. override a wrong --default-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. / localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. scope. '12 Rue de Rivoli, 75001 Paris' under en-US otherwise geocodes to Addison, Texas (ZIP 75001). Abstains when the default countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. is already consistent, when no countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. is, or when more than one is. ON by default (promoted 2026-08-05); pass --no-postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.-coherencecoherenceThe property of a parse whose resolved places form a consistent geographic hierarchy — the resolved locality really does sit inside the resolved region. to restore the un-overridden countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. scope.
--place-country-threshold [place-country-threshold]	number	0.9	Abstention threshold for --place-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.: below this calibrated confidence the prior is skipped. Default 0.9.
--format [format]	json | text | jsonld	json	Output format. "json" (default) emits the native machine-readable result; "text" prints a human summary; "jsonld" emits a schema.org Place/PostalAddress/GeoCoordinates JSON-LD object (the web's native address format).

mailwoman openapi

Emit the native @mailwoman/api OpenAPI document

mailwoman openapi [options]

Flag	Type	Default	Description
--flavor [flavor]	3.1 | 3.0	3.1	OpenAPI flavor: 3.1.0 (default) or the 3.0.3 diet
--out [out]	string	—	Write to this path instead of stdout

mailwoman parse

mailwoman parse [options] <address...>

Argument	Required	Description
<address...>	Yes	A formattedinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. postal address

Flag	Type	Default	Description
--debug	boolean	false	Enable verbose debugging output
--input-mode [input-mode]	fragmented | formatted	—	Input registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. (Decision A): 'fragmentedinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise.' feeds the evidence-bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. channels (map-search registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise.), 'formattedinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise.' runs them off (validation/record registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise.). Unset → derived from the input's shape.
--locale [locale]	string	en-US	LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. tag matching a weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. package (en-US, fr-FR). Default en-US.
--default-country [default-country]	string	—	ISO-3166 countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. to scope the WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. when the parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. carries no resolved countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. node — e.g. 'US' so a bare 'NY' resolves to the US state, not a higher-priority foreign homonym. Requires --resolve. Defaults from --localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.'s regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. subtag (en-US → US); pass 'none' to disable the filter and let ranking alone decide.
--country-scope [country-scope]	auto | locale | none	auto	Whether the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-inferred countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. scopes the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.: 'localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.' always, 'none' never, 'auto' (default) only on the FTS backend — the candidate backend ranks countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.-agnostically, so 'auto' leaves it unscoped. Pin 'localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.' or 'none' to hold countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. policy fixed while changing backends. An explicit --default-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. outranks all three.
--no-admin-coherence	boolean	true	Joint admin-consistency re-pick during --resolve (#263/#822: 'Portland, ME' binds to Maine, not Messina). ON by default (#895); pass --no-admin-coherencecoherenceThe property of a parse whose resolved places form a consistent geographic hierarchy — the resolved locality really does sit inside the resolved region. to restore the greedy population-first ranking.
--no-postcode-country-coherence	boolean	true	#42: let a (postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one., localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.) pair that is geographically consistent in exactly ONE countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. override a wrong --default-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.. '12 Rue de Rivoli, 75001 Paris' under en-US otherwise resolves to Paris, Texas. Abstains when the default countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. is already consistent, when no countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. is, or when more than one is. ON by default (promoted 2026-08-05); pass --no-postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.-coherencecoherenceThe property of a parse whose resolved places form a consistent geographic hierarchy — the resolved locality really does sit inside the resolved region. to restore the un-overridden countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. scope. Requires --resolve.
--neural	boolean	false	[Legacy] Force the neural-classifier-only path (skips StagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). 1 + 2 + 2.5 of the pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package.).
--no-poi	boolean	true	poi_query detection (poiQueryKind flag). DEFAULT-ON since 2026-07-20 (promotion batteryacceptance batteryThe packaged promotion harness — golden floors with noise-honest margins, fragment boards with lowercase legs, invariance, gauntlet, canaries, evidence ablation, capability manifest — run identically for our own promotes and (with per-customer canaries + the EWC guarantee gate) at fine-tune-engagement delivery.: 0/4507 golden misroutes, 6/6 demo presets byte-identical). Pass --no-poipoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer. to restore the pre-flag address-only kind classification.
--download-weights	boolean	false	If the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.'s neural weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. aren't installed, download them into ~/.cache/mailwoman/weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. without prompting, then parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates.. Non-interactive-safe (CI, pipes).
--degraded	boolean	false	Run the structural pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. stagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). only (normalizenormalizeStage 1 of the runtime pipeline: deterministic input preprocessing (Unicode NFC, punctuation normalization, whitespace collapse). Returns a NormalizedInput with an offsetMap that maps normalized positions back to the raw input., query-shape, kind, grouper) without the neural encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters)., even when weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. are installed. A stderr banner names what's degraded.
--format [format]	json | tuple | xml	json	Output projection.
--model [model]	string	—	Explicit modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'.onnxONNX (Open Neural Network Exchange). An open format for machine learning models that enables interoperability between training frameworks and inference runtimes. Mailwoman ships its trained model as an ONNX file so it can run in Node.js and the browser via onnxruntime. path (--neural only). Overrides --localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. resolution.
--tokenizer [tokenizer]	string	—	Explicit tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses..modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' path (--neural only). Overrides --localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. resolution.
--policy [policies...]	string[]	—	Per-component policy override, repeatable. <component>=<mode> where mode is one of: rule_only, neural_only, both, neural_preferred, rule_preferred. Requires --neural.
--resolve	boolean	false	Run the parsed tree through the WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. (PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). 4.3) — decorates matched nodes with wofWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.:<id> + lat/lon. Requires --neural.
--resolve-db [resolve-db]	string	—	Path to a WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. SQLite distribution for --resolve. Defaults to $MAILWOMAN_WOF_DB; errors if neither is set.
--no-street-evidence-rerank	boolean	true	#727 phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4c: rerank the STREETstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. on BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. name-existence evidence (FR streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-centroids). DEFAULT-ON: a no-op unless a v3+ spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree.-headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' + streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-centroids-fr.db are both present (byte-stable otherwise). Splices only an atlas-confirmed streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. into the argmax tree. Pass --no-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-evidence-rerank to disable.
--candidates [candidates]	number	—	Surface up to N alternative resolutions per resolved node (Springfield-class disambiguation). Requires --resolve. Output format-dependent: json emits node.alternatives arrays, xml emits <alternative> child elements, tuple unchanged.
--benchmark [benchmark]	number	—	Run the pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. N times against the input and emit per-stagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). p50/p95/p99 + total wall + heap delta. 5-iteration warmupwarmupThe early phase of training where the learning rate ramps up from 0 to its peak value before cosine decay. Mailwoman uses a linear warmup. is excluded from the stats. Default path only (incompatible with --policy).

mailwoman poi

mailwoman poi [options] <query...>

Argument	Required	Description
<query...>	Yes	A POI-shaped query, e.g. 'fire hydrant near Springfield'

Flag	Type	Default	Description
--locale [locale]	string	en-US	LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. tag matching a weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. package (en-US, fr-FR). Default en-US.
--db [db]	string	—	Path to a sealed poipoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer..db layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. (mailwoman gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. build poipoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer.). When set, the matched intent is EXECUTED against it (results attached, or an anchor_required abstain). Absent = intent-only mode: the subject is still extracted and the build-local abstain (requires_build_local_layer) still fires.
--overpass	boolean	false	Additionally print an OverpassQL export block for the matched intent (spec §1: export-only — mailwoman never runs the query itself). A category with no @mailwoman/poipoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer.-taxonomy osmTag mapping prints a message instead of throwing.
--json	boolean	false	Dump the raw POIIntentOutcome as JSON instead of the human-readable summary.
--resolve-db [resolve-db]	string	—	Path to a WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. admin SQLite distribution for anchor resolution ('near Springfield IL' -> lat/lon). Defaults to $MAILWOMAN_WOF_DB, else the standard per-deployment shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. set under $MAILWOMAN_DATA_ROOT (same default mailwoman geocode uses). Missing entirely -> anchors stay coordinate-less (a note is printed) and --db queries abstain anchor_required.
--candidate-db [candidate-db]	string	—	Path to a byte-range candidate.db (build-candidate.ts) for anchor resolution — the demo-parity, population-first backend. Defaults to $MAILWOMAN_CANDIDATE_DB; when present it wins over --resolve-db.

mailwoman reverse

mailwoman reverse [options] <coordinate...>

Argument	Required	Description
<coordinate...>	Yes	Two positional values, latitude then longitude, in WGS-84 decimal degrees (e.g. 40.7128 -74.0060).

Flag	Type	Default	Description
--admin-db [admin-db]	string	—	Path to the admin gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. SQLite DB (must carry the package-built place_bbox R*TreeR*TreeSQLite's spatial index of bounding boxes, enabling fast geographic range and nearest-neighbour queries in the resolver.). Defaults to $MAILWOMAN_WOF_ADMIN_DB.
--polygons-db [polygons-db]	string	—	Path to the polygon sidecar DB (wofWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.-polygons.db, table polygons(id, geom)). Without it every result is containment: approximate. Defaults to $MAILWOMAN_WOF_POLYGONS_DB.
--format [format]	json | text	json	Output format. "json" emits a machine-readable object; "text" prints a human-readable hierarchy.

mailwoman serve

mailwoman serve [options]

Flag	Type	Default	Description
--port [port]	number	3000	The port to listen on
--host [host]	string	0.0.0.0	The network interface to bind to
--cpus [cpus]	number	—	The number of worker processes to fork. Default: every available core.

mailwoman data

mailwoman data pull

mailwoman data pull [options] <bundle...>

Argument	Required	Description
<bundle...>	Yes	Bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. name(s) to pull: candidate, poipoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer., fr, us

Flag	Type	Default	Description
--dry-run	boolean	false	Print the download plan; touch no network and write nothing
--only [only]	string	—	Only pull artifacts whose remote/local path or state slug contains this substring (e.g. --only nh)
--force	boolean	false	Re-download even when a local copy already appears present
--data-root [data-root]	string	—	Override the data root for this pull (default: $MAILWOMAN_DATA_ROOT or the built-in default)

mailwoman data status

mailwoman data status [options] [bundle...]

Argument	Required	Description
[bundle...]	No	Bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. name(s) to report on. Default: every bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. (candidate, poipoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer., fr, us)

Flag	Type	Default	Description
--check-remote	boolean	false	HEADattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. each present artifact's live Content-Length via APIClient instead of trusting the recorded size
--data-root [data-root]	string	—	Override the data root (default: $MAILWOMAN_DATA_ROOT or the built-in default)

mailwoman skill

mailwoman skill install

mailwoman skill install [options]

Flag	Type	Default	Description
--dest [dest]	string	—	Directory to install into — writes <dest>/.claude/skills/mailwoman/. Default: the current directory.

mailwoman clients

mailwoman clients generate

Generate + verify the Python and Rust API clients from the emitted OpenAPI specs

mailwoman clients generate [options]

Flag	Type	Default	Description
--out-dir [out-dir]	string	—	Output root. Default <repo>/clients-build (gitignored)
--skip-verify	boolean	false	Skip uv build/import-check + cargo check --examples (dev only — an unverified pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. must never stand in as a release proof)

mailwoman registry

mailwoman registry convert tx-hhsc

mailwoman registry convert tx-hhsc [options]

Flag	Type	Default	Description
--src [src]	string	—	TX HHSC nursing-facilities TSV (default $MAILWOMAN_DATA_ROOT/record-matcher/sources/…)
--out [out]	string	environment-dependent	Output OaRow JSONL path

mailwoman registry dedup-ceiling

mailwoman registry dedup-ceiling [options]

Flag	Type	Default	Description
--sources [sources]	string	—	Record-matcher sources dir (default $MAILWOMAN_DATA_ROOT/record-matcher/sources)
--cap [cap]	number	50000	Providers sampled from the registry
--state [state]	string	TX	State filter
--tau [tau]	number	0.7	Org-name Jaccard collision threshold
--out-md [out-md]	string	—	Also write the markdown report here

mailwoman registry gold-set-sample

mailwoman registry gold-set-sample [options]

Flag	Type	Default	Description
--sources [sources]	string	—	Record-matcher sources dir (default $MAILWOMAN_DATA_ROOT/record-matcher/sources)
--cap [cap]	number	200000	Providers sampled from the registry
--state [state]	string	TX	State filter
--tau [tau]	number	0.7	Org-name Jaccard collision threshold
--n [n]	number	300	Adjudication sample size (deterministic stride sample)
--out-jsonl [out-jsonl]	string	—	Write the sampled pairs here as JSONL

mailwoman registry matcher-scale

mailwoman registry matcher-scale [options]

Flag	Type	Default	Description
--sizes [sizes]	string	10000,50000,100000,250000,500000	Comma-separated record counts to sweep
--dup [dup]	number	3	Average records per distinct place
--em	boolean	false	Fit the FS m/u with EMexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed. per size (slower)
--out-md [out-md]	string	—	Also write the markdown report here

mailwoman registry run

mailwoman registry run [options] [csv...]

Argument	Required	Description
[csv...]	No	Path(s) to a CSV file of contact / organization records. Optional when --sources is given (multi-source mode supplies the inputs).

Flag	Type	Default	Description
--mapping [mapping]	string	—	Column mapping: a path to a JSON file (or inline JSON) of { id?, source?, name?, organization?, address?, phone?, email? }, where each field names the CSV column(s) to draw from. Merged over the base (the built-in default, or --infer-mapping's inferenceinferenceRunning the trained model on new input to get predictions, as opposed to training, which produces the model. In Mailwoman that means a small transformer encoder reads an address string and classifies every token — house number, street, locality, region, postcode, and the rest. A Who's On First gazetteer can feed soft location hints into the pass, but the model makes the final call on every label. Where a generative model writes text token by token, Mailwoman's output is a retrieval-augmented token classification: one label per input piece.); column names are matched case-sensitively.
--infer-mapping	boolean	false	Infer the column mapping from the header by keyword (best-effort — point it at any reasonably-named CSV). Used as the base instead of the built-in default; an explicit --mapping still merges on top. Single-CSV mode.
--sources [sources]	string	—	Multi-source mode: a path to a JSON file (or inline JSON) of [{ path, delimiter?, mapping, source?, limit? }] — each dataset gets its own column mapping + provenance labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag., all resolved into ONE entity set across sources with no shared key. An entity spanning ≥2 sources is a cross-dataset link. The positional CSV is ignored when --sources is set. Inputs are streamed as UNQUOTED delimited files (tab inferred from .tsv) — right for the big government TSVs; convert a quoted CSV first or use the single-CSV path for those.
--out [out]	string	—	Write the GeoJSON FeatureCollection here. Default: print to stdout.
--map-out [map-out]	string	—	Also write a standalone HTML map of the resolved entities here (MapLibre + the house Protomaps basemap). Points are sized by records-merged and colored by cross-dataset-link status. SERVE IT OVER localhost (e.g. npx serve), don't open the file directly — the basemap tiles are CORS-restricted to localhost + the docs domain. Pairs naturally with --sources.
--no-train-em	boolean	true	Fit the Fellegi-SunterFellegi-SunterA probabilistic record linkage model that computes match probability from agreement-level log-likelihood ratios: log₂(m/u) where m is the probability of agreement given a true match and u is the probability of agreement by chance. Mailwoman learns m and u label-free via expectation-maximization. m/u + prior to the data with EMexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed. (labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.-free) before scoring. --no-train-emexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed. uses the seeds.
--threshold [threshold]	number	0	Link two records into one entity at or above this match weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. (bits). Higher = stricter. Default 0.
--max-block-size [max-block-size]	number	—	Skip + report blocks larger than this rather than scanning them (recallrecallOf the spans whose gold label is a given tag, the fraction the model found. High recall means few misses. Paired with precision to compute F1. vs cost). Default: scan all.
--reconcile	boolean	false	CoveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. reconciliation (#621): classify each resolved entity by which KIND of source its records spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. — enrolled (eligibility + funding), eligible-not-enrolled (the anti-join), or funded-not-eligible. Requires --sources where each spec carries role: "eligibility" | "funding". Prints a set-membership report to stdout; --out writes bucket-tagged GeoJSON, --map-out a bucket-colored map. A reconciliation, never a determination.
--source [source]	string	—	A provenance labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. stamped on every record (e.g. the dataset name).
--locale [locale]	string	en-US	LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. tag matching an installed weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. package. Default en-US.
--default-country [default-country]	string	—	ISO-3166 countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. to scope the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.. Defaults from --localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.'s regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. subtag (en-US → US).
--no-place-country	boolean	true	The #244 coarse-placercoarse-placerA lightweight int8 country classifier (~0.79 MB) that predicts which of a set of target countries an address belongs to, feeding a soft prior into resolver disambiguation. soft countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. prior (on by default). --no-place-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. disables it.
--resolve-db [resolve-db]	string	—	Path to a WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. admin SQLite distribution. Defaults to $MAILWOMAN_WOF_DB; errors if neither is set.
--data-root [data-root]	string	environment-dependent	Root directory for per-state address-point + interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.. Defaults to $MAILWOMAN_DATA_ROOT.

mailwoman registry scorer-eval

mailwoman registry scorer-eval [options] <kind>

Argument	Required	Description
<kind>	Yes	EvalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. kind (pairwise, clusteringclusteringThe final stage of entity resolution: resolve non-transitive pairwise match decisions (A↔B, B↔C, but not A↔C) into canonical entities via union-find with path compression. Each cluster of records becomes one resolved entity., cross-state, nppes-benchmark, …)

Flag	Type	Default	Description
--sources [sources]	string	—	Record-matcher sources dir (default $MAILWOMAN_DATA_ROOT/record-matcher/sources)
--wof [wof]	string	—	WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. admin SQLite path (default $MAILWOMAN_DATA_ROOT/wofWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations./admin-global-priority.db)
--data-root [data-root]	string	—	Per-state shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. root (default $MAILWOMAN_DATA_ROOT)
--out-md [out-md]	string	—	Also write the markdown report here
--state [state]	string	—	State filter (default TX)
--npis [npis]	number	—	pairwise/clusteringclusteringThe final stage of entity resolution: resolve non-transitive pairwise match decisions (A↔B, B↔C, but not A↔C) into canonical entities via union-find with path compression. Each cluster of records becomes one resolved entity./cross-state: NPIs sampled
--cap [cap]	number	—	dedup-ceiling/coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present.-reconciliation/cross-dataset/threshold-sweep: sample cap
--max [max]	number	—	vs-provided-coords: facilities geocoded (default 2000)
--max-npis [max-npis]	number	—	nppes-benchmark: NPIs sampled (default 300)
--tau [tau]	number	—	dedup-ceiling: org-name Jaccard collision threshold (default 0.7)
--seed [seed]	number	—	pairwise/clusteringclusteringThe final stage of entity resolution: resolve non-transitive pairwise match decisions (A↔B, B↔C, but not A↔C) into canonical entities via union-find with path compression. Each cluster of records becomes one resolved entity.: base PRNG seed (default 1)
--seeds [seeds]	number	—	pairwise/clusteringclusteringThe final stage of entity resolution: resolve non-transitive pairwise match decisions (A↔B, B↔C, but not A↔C) into canonical entities via union-find with path compression. Each cluster of records becomes one resolved entity.: splits averaged (default 8 / 4)
--split [split]	number	—	clusteringclusteringThe final stage of entity resolution: resolve non-transitive pairwise match decisions (A↔B, B↔C, but not A↔C) into canonical entities via union-find with path compression. Each cluster of records becomes one resolved entity.: train fraction of the NPI split (default 0.67)
--train-state [train-state]	string	—	cross-state: state the GBTGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline./LR train on (default TX)
--eval-state [eval-state]	string	—	cross-state: held-out state clustered (default CA)
--no-train-em	boolean	true	nppes-benchmark: EMexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed.-train the FS arms (--no-train-emexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed. uses seeds)
--legacy-join	boolean	false	nppes-benchmark: #694 A/B — pre-flip space-join + normalizeCase off
--candidate [candidate]	string	—	nppes-benchmark/threshold-sweep: a trained GBTGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline. TS module to grade as an extra arm
--dump-overmerges [dump-overmerges]	string	—	nppes-benchmark: write the #625 gold-set adjudication packet here
--h3-res [h3-res]	number	—	nppes-benchmark: H3H3Uber's hexagonal hierarchical geospatial indexing system. Mailwoman uses H3 cells at resolution 9 (~0.03 km²) for geo-first blocking in the matcher and for stable address primary keys in @mailwoman/address-id. resolution for the org-name-h3H3Uber's hexagonal hierarchical geospatial indexing system. Mailwoman uses H3 cells at resolution 9 (~0.03 km²) for geo-first blocking in the matcher and for stable address primary keys in @mailwoman/address-id. grain (default 11)
--parallel-geocode	boolean	false	nppes-benchmark: geocode across a worker pool (mailwoman/geocode-stream)
--geo-concurrency [geo-concurrency]	number	—	nppes-benchmark: worker-pool concurrency (default 2)
--model [model]	string	—	nppes-benchmark: modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'-swap ONNXONNX (Open Neural Network Exchange). An open format for machine learning models that enables interoperability between training frameworks and inference runtimes. Mailwoman ships its trained model as an ONNX file so it can run in Node.js and the browser via onnxruntime. path (requires --modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'-card)
--tokenizer [tokenizer]	string	—	nppes-benchmark: modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'-swap tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses. path
--model-card [model-card]	string	—	nppes-benchmark: modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'-swap modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'-card path
--no-corpus-frequency	boolean	true	cross-dataset: build the corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus.-wide address-frequency table (--no-corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus.-frequency skips)
--out-geojson [out-geojson]	string	—	coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present.-reconciliation/cross-dataset: also write the GeoJSON artifact here

mailwoman registry train-scorer

mailwoman registry train-scorer [options] <variant>

Argument	Required	Description
<variant>	Yes	Modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' variant (gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline., cross-gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline., org-cross-gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.)

Flag	Type	Default	Description
--sources [sources]	string	—	Record-matcher sources dir (default $MAILWOMAN_DATA_ROOT/record-matcher/sources)
--state [state]	string	—	gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline./cross-gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.: state filter (default TX)
--npis [npis]	number	—	gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline./cross-gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.: NPIs sampled (default 3000 gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline. / 2000 cross-gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.)
--cap [cap]	number	—	org-cross-gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.: Care Compare facilities sampled (default 6000)
--cost [cost]	number	—	gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.: negative-class up-weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. (#625 cost-sensitive; 1 = symmetric default)
--precision-bar [precision-bar]	number	—	cross-gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline./org-cross-gbtGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.: held-out pairwise precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. bar (#655 rule; default 0.95)
--out [out]	string	—	Output TS module path (each variant has a registry/modelsneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' default)
--locale [locale]	string	en-US	WeightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. (loaded by the geocoder + stamped in the meta)
--date [date]	string	—	TrainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. date stamped into the meta (for reproducible commits)
--wof [wof]	string	—	WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. admin SQLite path (default $MAILWOMAN_DATA_ROOT/wofWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations./admin-global-priority.db)
--data-root [data-root]	string	—	Per-state shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. root (default $MAILWOMAN_DATA_ROOT)

mailwoman registry viz

mailwoman registry viz [options] <figure>

Argument	Required	Description
<figure>	Yes	Figure id (cross-dataset-map, geocode-firstgeocode-firstThe matcher's core design principle: resolve addresses to geographic coordinates first, then compare the resolved places — not the raw address strings. Two records at the same coordinates match even if one says '123 Main St' and the other says '123 MAIN STREET.'-surface, source-provenance-map, yardstick-figure)

Flag	Type	Default	Description
--in [in]	string	—	cross-dataset-map: the cross-dataset-links GeoJSON
--cross-agency-only	boolean	false	cross-dataset-map: keep only entities spanning >1 agency (FCC datasets count as one)
--lambda [lambda]	number	—	geocode-firstgeocode-firstThe matcher's core design principle: resolve addresses to geographic coordinates first, then compare the resolved places — not the raw address strings. Two records at the same coordinates match even if one says '123 Main St' and the other says '123 MAIN STREET.'-surface: illustrative prior λ (default 0.02)
--state [state]	string	—	source-provenance-map: state, lowercase postal (default ny)
--db [db]	string	—	source-provenance-map: address-point DB path
--nad-mod [nad-mod]	number	—	source-provenance-map: keep ~1/N of NADNAD (National Address Database). A US Department of Transportation dataset of structured address points, added to the training corpus as a major source of real US addresses. points (default 700)
--oa-mod [oa-mod]	number	—	source-provenance-map: keep ~1/N of OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. points (default 120)
--cap [cap]	number	—	source-provenance-map: per-source marker cap (default 7000)
--out-html [out-html]	string	—	HTML figures: output path (each figure has a /tmp default)
--out-svg [out-svg]	string	—	yardstick-figure: output SVG path (default docs/records/evalsevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error./charts/dedup-yardstick.svg)

Exit codes

Every command shares one exit-code contract, owned by useCommandTask in mailwoman/cli-kit.

Code	Meaning	Next step
0	The command completed. A command with a verdict returns 0 for a pass.	None.
1	The command threw, or its verdict is a failure. The message is on stderr.	Read the message. Guidance-grade failures print one line and name the fix.

Two behaviors are worth stating because they are not failures.

• mailwoman doctor exits 0 when the core checks pass, even when every optional data layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. is missing. Parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. works without them.
• mailwoman parse degrades to the structural stagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). when the neural weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. are absent, prints a warning on stderr, and still exits 0. Standard output stays machine-parseable.

Commands this page does not cover

These groups build the data and the modelsneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'. They read paths and databases that only exist inside a checkout of the repository, and they are documented in the repository rather than here. The two build tutorials under See also run the ones a self-hosting reader needs.

Group	Commands	Purpose
mailwoman corpus	19	Builds and audits the BIO-labeled trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus..
mailwoman coverage	1	Builds the demo map's address-coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. overlay tiles.
mailwoman dev	10	Repository maintenance: source generation, fixture capture, lint passes.
mailwoman eval	17	Runs the evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. gates that decide whether a modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' ships.
mailwoman filer	1	Record-linkage evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. over regulatory filings.
mailwoman gazetteer	44	Builds every gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. artifact, including the candidate and admin databases.
mailwoman gnaf	1	Assembles the Australian G-NAFG-NAF (Geocoded National Address File). Australia's authoritative open address register (CC-BY-licensed), used as a training source for Australian addresses. address registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise..
mailwoman placer	5	Trains and evaluates the coarse countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. placer.
mailwoman release	1	StagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). model weightsmodel weightsThe learned parameters of the neural classifier, shipped as ONNX files in the @mailwoman/neural-weights-* packages. Weights are locale-specific bundles that include the model, tokenizer, and a model-card.json metadata file. for a release.
mailwoman situs	5	Builds the US rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. address-point and interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row..
mailwoman tiger	4	Processes US Census TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data./Line road and boundary data.
mailwoman tiles	1	Publishes vector tiles to the demo map's bucket.
mailwoman wof	5	Prepares and inspects the Who's On FirstWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. source tree.

Rationale

This page is generated rather than written because a hand-maintained flag table is wrong the day a flag changes, and nothing catches it. The generator reads the same Pastel and Commander code that builds the binary, so a flag string here is the flag string --help prints. A test asserts the committed page against a fresh render, which turns a stale page into a failing build.

The scope split is deliberate. Publishing all 134 commands would bury the 20 that run against an installed package under trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. and dataset tooling that requires the repository, its data root, and hours of wall clock. The generator refuses to run if it meets a command group it has never been told about, so the boundary is a decision someone makes rather than an omission.

See also

• Library API — the same pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package., called from TypeScript.
• HTTP APIs — the server surfaces, including mailwoman serve.
• Runtime flags — the environment variables these commands read.
• Understand a parse — mailwoman parse, executed.
• Geocode a CSV — mailwoman data pull and mailwoman geocode, executed.
• Build the US dataset — the gazetteer and situs groups, executed.