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 151 commands. This page documents the 23 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

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)..

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; defaults from $MAILWOMAN_FST_BIN.
--json	boolean	false	Emit 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

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 carries the one command that closes it.

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.

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-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.
--postcode-shape-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. shape exclusion/demotion.
--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.
--capital-tier	boolean	—	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 (default on); --no-capital-tier disables it.
--variant-alias-exemption	boolean	—	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 (default on); --no-variant-alias-exemption disables it.
--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 openapi

Emit the native @mailwoman/api OpenAPI document.

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.

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
--postcode-shape-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. 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 gate, 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
--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

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.

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-neighbour 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

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 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 names the one you are missing.

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 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..

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	—	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. config whose country_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. decides admission
--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 shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. instead of reading the cache (costs minutes)
--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 contract (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.-contract.mdx); this says how much of the root implements it.

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 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)
--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.

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

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

mailwoman skill

mailwoman skill install

Install the packaged Mailwoman skill.

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

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.

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.

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.

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 shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. sizes.

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

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.

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	—	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. state
--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 shards (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.

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	—	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
--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.

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 contract, 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 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	11	Repository maintenance: source generation, fixture capture, lint passes.
mailwoman eval	21	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	52	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. 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 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 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, which turns a stale page into a failing build.

The scope split is deliberate. Publishing all 151 commands would bury the 23 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.