CLI

Scope

This page is the flag interface 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 has 187 commands. This page documents the 31 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 states which variable it reads.
• A value in angle brackets in a synopsis is required. A value in square brackets is optional.

This page lists each command's synopsis and flags. For executed invocations with their real output, follow the tutorials and how-to guides linked under See also.

Top-level commands

mailwoman autocomplete

Return ranked place-name completions for a prefix from the FST gazetteeradmin FSTA finite-state transducer encoding Who's On First admin place names (countries, regions, localities, postcodes) for fast gazetteer lookup and emission priors at inference time. Ships to the browser (~9 MB for 94K US admin places)..

text

mailwoman autocomplete [options] [prefix...]

Argument	Required	Description
[prefix...]	No	Prefix string to complete.

Flag	Type	Default	Description
--limit [limit]	number	10	Maximum number of completions.
--fst [fst]	string	—	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. The default comes from $MAILWOMAN_FST_BIN.
--json	boolean	false	Emit { engine, entries } as JSON 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

Check whether this machine can run mailwoman, and what each gap costs you. Runtime first (node, 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.), then the 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., then the optional data layerslayerOne 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. geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. needs. A missing 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 reported, never fatal, and every failing line prints the one command that closes it. Then the license posture: the branch of mailwoman's license that applies to this installation, and the obligations each attached 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.'s recorded license imposes (attribution, share-alike, source offer).

text

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, consequence?, 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 + consequence aid machine consumers). With --verbose, an environment array of { key, value, source } is added.
--verbose	boolean	false	Also print every path and environment variable the checks resolved (data root, candidate.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. databases, 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.) so a surprising verdict can be traced to the setting that caused it. No -v short form: the root program owns -v for --version.

mailwoman geocode

Turn an address into a coordinate: 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. it, then resolve the parts against the 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. and the 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./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. databases.

text

mailwoman geocode [options] [address...]

Argument	Required	Description
[address...]	No	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. Omit when using --stdin.

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, such as en-US or fr-FR.
--bias [bias]	string	—	Soft proximity-bias points: lat,lon[:weight];lat,lon.
--default-country [default-country]	string	—	ISO-3166 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. 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. Pass none to disable it.
--country-scope [country-scope]	auto | locale | none	auto	Apply the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-inferred 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. scope automatically, always, or never.
--resolve-db [resolve-db]	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 distribution.
--candidate-db [candidate-db]	string	—	Demo-parity byte-range candidate database.
--data-root [data-root]	string	—	Root containing the 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., 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., 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., and other data databases.
--address-points-db [address-points-db]	string	—	Explicit address-point SQLite database, bypassing regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. selection.
--interpolation-db [interpolation-db]	string	—	Explicit 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 database, bypassing regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. selection.
--interp-calibration [interp-calibration]	number	—	Force one 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. uncertainty calibration multiplier.
--locale-country-prior	boolean	false	Use a withheld localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 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. as a soft 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. ranking prior.
--no-gazetteer-prior	boolean	true	Feed the gazetteer FSTadmin FSTA finite-state transducer encoding Who's On First admin place names (countries, regions, localities, postcodes) for fast gazetteer lookup and emission priors at inference time. Ships to the browser (~9 MB for 94K US admin places). prior to 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.; --no-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.-prior disables it.
--no-venue-head-prior	boolean	true	Feed the venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label.-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. prior, from @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's 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.-word table, to 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.; --no-venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label.-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.-prior disables it.
--venue-head-bias-scale [venue-head-bias-scale]	number	2	Multiplier on the venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label.-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. table's biases.
--no-street-morphology-prior	boolean	true	Bias a trailing streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-type affix toward 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. labelscomponent 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. when its segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. opens with a house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales.; --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.-morphology-prior disables it.
--no-place-country	boolean	true	Use the 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. 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; --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.
--no-postcode-country-coherence	boolean	true	Allow coherent postcodepostcodeThe country-specific postcode (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. evidence to override a wrong 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.
--no-fork-entity	boolean	true	Probe POI data for exact entities when a fork 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. does not resolve.
--no-postcode-shape-coherence	boolean	true	Exclude a postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. 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. whose shape fits no postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. syntax of a 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. the address mentions.
--postcode-containment-coherence	boolean	false	Opt into postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.-centroid localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. reranking.
--no-admin-containment-rerank	boolean	true	RegionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.-qualifier containment reranking of localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. candidates; --no-admin-containment-rerank disables it.
--no-dependent-locality-containment	boolean	true	Resolve a parsed dependent localitydependent localityA sub-locality (neighborhood or borough) hierarchically inside a larger locality — e.g. Brooklyn within New York City. Provides finer geographic specification below the primary locality. inside its parent and answer its point; --no-dependent-localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.-containment disables it (#2804).
--capital-tier [capital-tier]	auto | required | off	auto	Bounded national-capital promotion on bare citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. names: auto (skip when the capitals reference is missing), required (fail when it is missing), or off.
--variant-alias-exemption [variant-alias-exemption]	applied | not_applied	applied	Whether own-name variant aliases keep their holder's rank in cross-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. contests: applied or not_applied.
--place-country-threshold [place-country-threshold]	number	0.9	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. abstention threshold.
--format [format]	json | text | jsonld	json	Output format.
--json	boolean	false	Shorthand for --format json.
--text	boolean	false	Shorthand for --format text.
--jsonld	boolean	false	Shorthand for --format jsonld.
--debug	boolean	false	Open the interactive 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./resolution/map view.
--debug-size [debug-size]	string	120x36	Frame size for non-TTY debug rendering.
--stdin	boolean	false	Read one address per line and emit one JSON object per line using one warm session.
--timing	boolean	false	Write startup, initialization, and per-address phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). timings to stderr.
--tiles [tiles]	string	—	PMTiles archive for the debug map pane.

mailwoman license

Mint, issue, verify, adopt and refresh commercial license keys. keygen writes an Ed25519 signing pair under $MAILWOMAN_CONFIG_ROOT/license and prints the public key with its id. issue signs a key for a licensee. verify checks a tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. offline against the public keys this build trusts. register prints the well-known key file the shipped 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. derives. adopt <token> --secret <s> writes a purchased key to $MAILWOMAN_CONFIG_ROOT/license/key and its refresh secret beside it. refresh fetches the current key after a renewal. Without a key the AGPL-3.0-only branch applies — mailwoman doctor reports which branch applies and why.

text

mailwoman license [options] <action> [argument]

Argument	Required	Description
<action>	Yes	One of: keygen, issue, verify, 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., adopt, refresh, declare, evaluate, attribution.
[argument]	No	adopt: the tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. to adopt.

Flag	Type	Default	Description
--lid [lid]	string	—	refresh: the license id, when not reading $MAILWOMAN_CONFIG_ROOT/license/refresh.json.
--secret [secret]	string	—	adopt: the refresh secret from the purchase page or the first email, stored beside the key. refresh: the secret, when not reading the credentials file.
--licensee [licensee]	string	—	issue: who holds the license, as the doctor should print it.
--intent [intent]	string	—	declare: the declaration's intent. open-source gives --project. The others give --organization and --email.
--name [name]	string	—	declare, evaluate: the project or the person the tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. is issued to, as the doctor prints it.
--project [project]	string	—	declare --intent open-source: the project's public source URL.
--organization [organization]	string	—	declare: the non-profit, university or school.
--email [email]	string	—	declare, evaluate: the address the tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. is sent to. For a declaration it is an address at the organization.
--expires [expires]	string	—	issue: the last day the key is valid, inclusive. Omit for a key with no expiry.
--scope [scope]	string	all	issue: all, or a comma-separated list of the packages the agreement covers.
--major [major]	string	—	keygen: the mailwoman major version the key id is prefixed with. Defaults to this build's.
--key [key]	string	—	verify: the tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. to check. Defaults to $MAILWOMAN_LICENSE_KEY.
--signing-key [signing-key]	string	—	issue: the private key PEM. Defaults to $MAILWOMAN_CONFIG_ROOT/license/signing-key.pem.
--online	boolean	false	verify: also ask mailwoman.ai's well-known 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. whether the key id is still listed, and the license worker whether a self-service license still stands.
--write	boolean	false	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.: write the well-known file under docs/static instead of printing it.
--json	boolean	false	Emit the result as JSON.

mailwoman openapi

Emit the native @mailwoman/api OpenAPI document.

text

mailwoman openapi [options]

Flag	Type	Default	Description
--flavor [flavor]	3.1 | 3.0	3.1	OpenAPI 3.1.0, or the compatibility-oriented 3.0.3 document.
--out [out]	string	—	Write to this path instead of stdout.

mailwoman parse

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. the parts of an address — house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales., streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. — without looking anything up: the output is your input, segmented and tagged. mailwoman geocode runs this same 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., then resolves those parts against the 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. to produce a coordinate.

text

mailwoman parse [options] <address...>

Argument	Required	Description
<address...>	Yes	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 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.
--locale [locale]	string	en-US	BCP-47 localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.
--default-country [default-country]	string	—	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. 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
--country-scope [country-scope]	auto | locale | none	auto	LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 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.-scoping policy
--no-admin-coherence	boolean	true	Joint admin consistency
--no-postcode-country-coherence	boolean	true	PostcodepostcodeThe country-specific postcode (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. consistency
--no-postcode-shape-coherence	boolean	true	PostcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. shape consistency
--postcode-containment-coherence	boolean	false	PostcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. containment reranking
--neural	boolean	false	Use neural-only path
--no-poi	boolean	true	Enable POI query detection
--download-weights	boolean	false	Download missing 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.
--degraded	boolean	false	Run structural stagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale check, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). only
--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.' path
--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. path
--policy [policy...]	string[]	—	Repeatable component policy override, <component>=<neural_only|both>
--resolve	boolean	false	Resolve parsed nodes against 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.
--resolve-db [resolve-db]	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. SQLite distribution
--no-street-evidence-rerank	boolean	true	Rerank streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. from atlas evidence
--candidates [candidates]	number	—	Alternative resolutions per node
--benchmark [benchmark]	number	—	Benchmark iteration count

mailwoman poi

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. and execute a 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.-shaped query

text

mailwoman poi [options] <query...>

Argument	Required	Description
<query...>	Yes	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. query

Flag	Type	Default	Description
--locale [locale]	string	en-US	BCP-47 localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.
--db [db]	string	—	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.
--overpass	boolean	false	Print an OverpassQL export block
--json	boolean	false	Emit raw JSON
--resolve-db [resolve-db]	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. database for anchor resolution
--candidate-db [candidate-db]	string	—	Candidate database for anchor resolution

mailwoman reverse

Resolve a WGS-84 coordinate to its containing 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. administrative hierarchy.

text

mailwoman reverse [options] <lat> <lon>

Argument	Required	Description
<lat>	Yes	Latitude in WGS-84 decimal degrees.
<lon>	Yes	Longitude in WGS-84 decimal degrees.

Flag	Type	Default	Description
--admin-db [admin-db]	string	—	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 carrying the place_bbox R*TreeR*TreeSQLite's spatial index of bounding boxes, enabling fast geographic range and nearest-neighbor queries in the resolver..
--polygons-db [polygons-db]	string	—	Optional polygon sidecar. Without it, containment is approximate.
--format [format]	json | text	json	Machine-readable JSON or a human-readable hierarchy.

mailwoman serve

Run the Mailwoman HTTP server

text

mailwoman serve [options]

Flag	Type	Default	Description
--port [port]	number	3000	Port to listen on
--host [host]	string	0.0.0.0	Network interface to bind
--cpus [cpus]	number	—	Worker processes. Default: every available core

mailwoman setup

The first run as one command: check the roots, 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. a sample address, list the tiers for your countries, and get a tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. by declaring, evaluating or buying.

text

mailwoman setup [options]

Flag	Type	Default	Description
--no-interactive	boolean	true	Ask which countries matter and which route to take. --no-interactive prints the report and exits.
--countries [countries...]	string[]	—	ISO 3166-1 alpha-2 codes of the countries whose tiers to list, such as GB or US.

mailwoman data

mailwoman data

Fetch the reference databases geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. needs — far too large to ship inside the npm package. data --list shows what exists, data pull <bundle> downloads one, data status reports what is already on disk, and mailwoman doctor reports the one you are missing.

text

mailwoman data [options]

Flag	Type	Default	Description
--list	boolean	false	List every downloadable 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.

mailwoman data activate

Select an installed installation, or restore the previous selection with --rollback

text

mailwoman data activate [options] [installation]

Argument	Required	Description
[installation]	No	An installation identity, inst-<16 hex>, from data status --json

Flag	Type	Default	Description
--rollback	boolean	false	Restore the generation the active one replaced
--data-root [data-root]	string	—	Override the data root

mailwoman data bom

Write the data bill of materials: one CycloneDX 1.5 component per artifact a release can deliver, carrying its license expression, the basis of that expression, and the publishers' conditions.

text

mailwoman data bom [options]

Flag	Type	Default	Description
--json	boolean	false	Write the document to stdout instead of to the file
--out [out]	string	—	Override the output path
--data-root [data-root]	string	—	Override the data root
--skip-inventory	boolean	false	Leave out the data root's manifested databases. The document then lists only the four bundlesevidence 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., and no component records attribution, source vintage or build revision

mailwoman data build

Build a 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. from source data, install it, and optionally activate it

text

mailwoman data build [options] <recipe>

Argument	Required	Description
<recipe>	Yes	The build recipe: osmOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names.-address-points

Flag	Type	Default	Description
--countries [countries]	string	—	Comma-separated ISO 3166-1 alpha-2 codes to build (e.g. --countries DE,NL)
--region [region]	string	—	One publisher regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. every requested 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 derived from (e.g. europe/dach). Default: each 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.'s own regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.
--dry-run	boolean	false	Print the plan and the prerequisite check without network access or data writes
--activate	boolean	false	Select each built 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. after it installs, after any source its 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. already selects
--data-root [data-root]	string	—	Override the data root (default: $MAILWOMAN_DATA_ROOT or the built-in default)
--geofabrik-host [geofabrik-host]	string	—	A mirror serving Geofabrik's regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. paths. Default: https://download.geofabrik.de/
--geoboundaries-host [geoboundaries-host]	string	—	A mirror serving the geoBoundaries API paths. Default: https://www.geoboundaries.org/
--json	boolean	false	Emit the plan, its problems by kind and the build's result as JSON

mailwoman data coverage

What mailwoman parsesaddress 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. and geocodes, per 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..

text

mailwoman data coverage [options]

Flag	Type	Default	Description
--countries [countries]	string	—	Comma-separated ISO alpha-2 codes. Omit for the countries that train.
--config [config]	string	—	Config that controls 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. admission through country_weights. Defaults to the config scope.config.json records for the Latin family's shipped graph.
--refresh	boolean	false	Recount the corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic extracts (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. instead of reading the cache (costs minutes)
--manifest [manifest]	string	—	Corpus MANIFEST.json to count with --refresh. Defaults to the newest manifest under the data root's corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic extracts (boundary stress, order variants, negative space). Managed by @mailwoman/corpus./versioned/.
--json	boolean	false	Emit the full report as JSON

mailwoman data inventory

Report every database in the data root and whether it records how it was built. layer_manifest is the interface (docs/engineering/reference/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.-interface.mdx). This report shows how much of the root implements it.

text

mailwoman data inventory [options]

Flag	Type	Default	Description
--data-root [data-root]	string	—	Override the data root
--depth [depth]	string	—	Directory levels to walk. Default 2
--all	boolean	false	List every artifact. The default shows only the summary
--json	boolean	false	Emit the report as JSON

mailwoman data migrate

Plan the registration of existing data files in the active selection (dry run only)

text

mailwoman data migrate [options]

Flag	Type	Default	Description
--dry-run	boolean	false	Print the plan. Required in this release
--data-root [data-root]	string	—	Override the data root
--json	boolean	false	Emit the plan as JSON

mailwoman data prune

Delete installed artifacts that no retained generation or running session references

text

mailwoman data prune [options]

Flag	Type	Default	Description
--yes	boolean	false	Delete the planned artifacts. Without it the command prints the plan and deletes none
--retain [retain]	string	—	Generations to keep, counting the active one. Default 2
--data-root [data-root]	string	—	Override the data root
--json	boolean	false	Emit the plan or the result as JSON

mailwoman data pull

Install published data bundlesevidence 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.

text

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 installation plan without network access or data writes
--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)
--host [host]	string	—	Mirror or private-registry base URL serving the same object keys as the public bucket (e.g. https://mirror.example/mailwoman/). Default: the public bucket.
--refuse [refuse...]	share-alike | unresolved	—	Decline a 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. whose recorded expression has this class of obligation (share-alike, unresolved). Repeatable. Default: $MAILWOMAN_REFUSE_OBLIGATIONS
--json	boolean	false	Emit the plan, its problems by kind and each artifact's outcome as JSON

mailwoman data sources

Read the publisher stamp on a downloaded 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.'s rows

text

mailwoman data sources [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. names. Default: 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
--data-root [data-root]	string	—	Override the data root

mailwoman data status

Report data 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. status

text

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. names. Default: 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	Check live artifact sizes
--data-root [data-root]	string	—	Override the data root
--json	boolean	false	Emit the status as JSON

mailwoman skill

mailwoman skill install

Install the packaged Mailwoman skill.

text

mailwoman skill install [options]

Flag	Type	Default	Description
--dest [dest]	string	—	Destination project directory

mailwoman clients

mailwoman clients generate

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

text

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 client build verification (development only)

mailwoman registry

mailwoman registry convert tx-hhsc

Convert the TX HHSC nursing-facilities TSV to OaRow JSONL.

text

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

Measure the irreducible over-merge rate for co-located providers.

text

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

Sample hard co-located name collisions for adjudication.

text

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

Measure matcher throughput and peak memory across corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic extracts (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. sizes.

text

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

Resolve records into matched entities

text

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

Argument	Required	Description
[csv...]	No	CSV input paths

Flag	Type	Default	Description
--mapping [mapping]	string	—	Column mapping JSON or path
--infer-mapping	boolean	false	Infer mapping from headers
--sources [sources]	string	—	Multi-source specification JSON or path
--out [out]	string	—	GeoJSON output
--map-out [map-out]	string	—	Standalone HTML map output
--no-train-em	boolean	true	Train 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. parametersparameterA 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.
--threshold [threshold]	number	0	Entity link threshold
--max-block-size [max-block-size]	number	—	Maximum scanned block size
--reconcile	boolean	false	Run 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
--source [source]	string	—	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.
--locale [locale]	string	en-US	BCP-47 localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.
--default-country [default-country]	string	—	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. 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
--no-place-country	boolean	true	Enable 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. prior
--resolve-db [resolve-db]	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 database
--data-root [data-root]	string	environment-dependent	Per-state database root

mailwoman registry scorer-eval

Run a registry scorer evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.

text

mailwoman registry scorer-eval [options] <kind>

Argument	Required	Description
<kind>	Yes	EvaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. kind

Flag	Type	Default	Description
--sources [sources]	string	—	Record-matcher sources directory
--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
--data-root [data-root]	string	—	Per-state database root
--out-md [out-md]	string	—	Markdown report path
--state [state]	string	—	State filter
--npis [npis]	number	—	NPIs sampled
--cap [cap]	number	—	Sample cap
--max [max]	number	—	Facilities geocoded
--max-npis [max-npis]	number	—	NPPES sample size
--tau [tau]	number	—	Collision threshold
--seed [seed]	number	—	PRNG seed
--seeds [seeds]	number	—	Splits averaged
--split [split]	number	—	Train fraction
--train-state [train-state]	string	—	State used for 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.' fitting
--eval-state [eval-state]	string	—	EvaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. state
--no-train-em	boolean	true	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 FS arms
--legacy-join	boolean	false	Use legacy join
--candidate [candidate]	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. module
--dump-overmerges [dump-overmerges]	string	—	Adjudication packet path
--h3-res [h3-res]	number	—	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
--parallel-geocode	boolean	false	Use geocode worker pool
--geo-concurrency [geo-concurrency]	number	—	Geocode concurrency
--model [model]	string	—	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
--tokenizer [tokenizer]	string	—	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	—	Model cardmodel cardA JSON metadata file (model-card.json) shipped with each weights bundle. It declares the model version, lineage, label set, required inference channels (anchor, gazetteer), calibration data, and training provenance. path
--no-corpus-frequency	boolean	true	Build corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic extracts (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. frequency table
--out-geojson [out-geojson]	string	—	GeoJSON artifact path

mailwoman registry train-scorer

Train a learned registry scorer.

text

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

Flag	Type	Default	Description
--sources [sources]	string	—	Record-matcher sources
--state [state]	string	—	State filter
--npis [npis]	number	—	NPIs sampled
--cap [cap]	number	—	Facility cap
--cost [cost]	number	—	Negative-class 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.
--precision-bar [precision-bar]	number	—	Held-out 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
--out [out]	string	—	Output module
--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.
--date [date]	string	—	Date of 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.' fitting
--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. database
--data-root [data-root]	string	—	Per-state database root

mailwoman registry viz

Render record-matcher figures.

text

mailwoman registry viz [options] <figure>

Argument	Required	Description
<figure>	Yes	Figure id

Flag	Type	Default	Description
--in [in]	string	—	Cross-dataset links GeoJSON
--cross-agency-only	boolean	false	Keep only cross-agency entities
--lambda [lambda]	number	—	Illustrative prior lambda
--state [state]	string	—	State PostcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.
--db [db]	string	—	Address-point database
--nad-mod [nad-mod]	number	—	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. sampling modulus
--oa-mod [oa-mod]	number	—	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. sampling modulus
--cap [cap]	number	—	Per-source marker cap
--out-html [out-html]	string	—	Output HTML path
--out-svg [out-svg]	string	—	Output SVG path

Exit codes

Every command shares one exit-code interface, owned by useCommandTask in packages/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 exceptional 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. The parser runs without the optional data layerslayerOne 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 parse degrades to the structural stagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale check, 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	27	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 extracts (boundary stress, order variants, negative space). Managed by @mailwoman/corpus..
mailwoman coverage	2	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	14	Repository maintenance: source generation, fixture capture, lint passes.
mailwoman eval	27	Runs the evaluationsevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. 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	2	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	60	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	2	StagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale check, 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 and admin-merges a pull request behind its guards.
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. databases.
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 train	1	Resolves the 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. configurations the 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.' trainer reads.
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 no check catches it. The generator reads the same command specifications that build the binary, so a flag string here is the flag string --help prints. A test asserts the committed page against a fresh render. A stale page therefore fails the build.

The scope split is deliberate. A page that covers all 187 commands would bury the 31 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-hint → 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.