CLI Reference

Command-line reference for the barangay PSGC tool: search, export, validate, batch operations, plugin enrichment, and info subcommands with examples.

Search

barangay search

Fuzzy search PSGC records. Results are reported along the full PSGC hierarchy: each of the nine administrative levels gets its own column, plus an rphicmsgb indicator summarising which levels resolved.

barangay search "Tongmageng, Sitangkai, Tawi-Tawi"

Options:

Parameter	Type	Default	Required	Description
--limit, -l	int	5	No	Maximum number of results
--threshold, -t	float	60.0	No	Minimum similarity score 0-100
--as-of	str	-	No	Historical date (YYYY-MM-DD)
--level, -L	str	-	No	Post-filter results to a specific admin level (e.g. province, barangay)
--match-hook	str	-	No	Name-levels to score against (repeatable); defaults to barangay
--format, -f	str	table	No	Output format - json or table
--plugin	str	-	No	Enable a plugin for enrichment (repeatable)

--level vs --match-hook. These are distinct, mirroring the Python API. --match-hook controls which name-levels participate in scoring (the most granular one determines the searched record set); --level is a post-filter on the result’s record type. To search provinces directly, use --match-hook province; to additionally restrict the returned record type, combine it with --level. Valid values for both are the nine PSGC levels: region, province, highly_urbanized_city, independent_component_city, component_city, municipality, submunicipality, special_geographic_area, barangay.

Table columns: Region, Province, HUC, ICC, Component City, Municipality, Sub-Mun, Special Geo, Barangay, rphicmsgb, PSGC ID, Score (plus any plugin.field columns). Columns that are blank for every result are omitted; the rphicmsgb indicator always records which levels resolved.

Examples:

# Basic search
barangay search "Tongmageng, Sitangkai, Tawi-Tawi"

# With custom limit and threshold
barangay search "Tongmageng" --limit 5 --threshold 70.0

# JSON output (resolved hierarchy + rphicmsgb + score + match_type)
barangay search "Tongmageng" --format json

# Historical data search
barangay search "Tongmageng" --as-of "2025-07-08" --format table

# Search a specific level (score provinces directly)
barangay search "Tawi" --match-hook province --level province

# Score against multiple name-levels
barangay search "Tawi-Tawi" --match-hook province --match-hook barangay

# With plugin enrichment
barangay search "Tongmageng" --plugin psgc-aux-data --format json

rphicmsgb indicator. A 9-character strip where each position holds the level’s letter when that level resolves, else 0:

Position	Letter	Level
1	r	Region
2	p	Province
3	h	Highly urbanized city
4	i	Independent component city
5	c	Component city
6	m	Municipality
7	s	Sub-municipality
8	g	Special geographic area
9	b	Barangay

For example, rp000m00b means the result spans region, province, municipality, and barangay.

Export

barangay export

Export data to JSON or CSV.

barangay export --model flat --format json --output data.json

Options:

Parameter	Type	Default	Required	Description
--model	str	flat	No	Data model - flat or extended (basic is no longer supported)
--format, -f	str	json	No	Output format - json or csv (CSV is flat-only)
--output, -o	str	stdout	No	Output file
--as-of	str	-	No	Historical date (YYYY-MM-DD)
--plugin	str	-	No	Enable a plugin for enrichment (repeatable; only with --model flat)

Note: The legacy --model basic nested-2-level model has been removed. CSV export is only available with --model flat; CSV columns are derived from the actual records (no hardcoded 3-column header).

Examples:

# Export flat data to JSON
barangay export --model flat --format json --output data.json

# Export flat data to CSV
barangay export --model flat --format csv --output data.csv

# Export historical data
barangay export --model flat --format json --as-of "2025-07-08" --output historical.json

# Export with plugin enrichment
barangay export --model flat --plugin psgc-aux-data --format json --output enriched.json

Info

barangay info version

Show current data version.

barangay info version

barangay info stats

Show record counts per PSGC hierarchy level.

barangay info stats

barangay info list

List records at a given hierarchy level, optionally restricted to the descendants of a parent.

# List all barangays
barangay info list barangay

# List provinces within a region (name or PSGC ID; abbreviations resolve)
barangay info list province --parent "BARMM"

# List barangays under a municipality
barangay info list barangay --parent "Sitangkai"

# List all cities (HUC + ICC + component city)
barangay info list cities

Argument:

Parameter	Type	Required	Description
level	str	Yes	One of region, province, highly_urbanized_city, independent_component_city, component_city, municipality, submunicipality, special_geographic_area, barangay, or cities

Options:

Parameter	Type	Default	Required	Description
--parent	str	-	No	Ancestor name or PSGC ID to filter descendants

Output columns: Name, Type, PSGC ID.

This generic command replaces the removed list-regions, list-municipalities, and list-barangays commands.

History

barangay history list-dates

List available historical dates.

barangay history list-dates

barangay history search-history

Search historical data. Uses the same hierarchy-loyal table/JSON shape as barangay search.

barangay history search-history "Tongmageng" --as-of "2025-07-08"

Options:

Parameter	Type	Default	Required	Description
--as-of	str	-	Yes	Historical date (YYYY-MM-DD)
--limit, -l	int	5	No	Maximum number of results
--threshold, -t	float	60.0	No	Minimum similarity score 0-100
--level, -L	str	-	No	Post-filter results to a specific admin level
--match-hook	str	-	No	Name-levels to score against (repeatable); defaults to barangay
--format, -f	str	table	No	Output format - json or table

Example:

barangay history search-history "Tongmageng" --as-of "2025-07-08" --limit 5 --format table

barangay history export-history

Export historical data.

barangay history export-history --as-of "2025-07-08" --model flat

Options:

Parameter	Type	Default	Required	Description
--as-of	str	-	Yes	Historical date (YYYY-MM-DD)
--model	str	flat	No	Data model - flat or extended (basic removed)
--format, -f	str	json	No	Output format - json or csv (CSV is flat-only)
--output, -o	str	stdout	No	Output file

Example:

barangay history export-history --as-of "2025-07-08" --model flat --format json --output 2025-07-08.json

Cache

barangay cache info

Show cache information.

barangay cache info

barangay cache clear

Clear cache directory.

barangay cache clear

barangay cache download

Download data to cache.

barangay cache download

Options:

Parameter	Type	Default	Required	Description
--date	str	-	No	Date to download (YYYY-MM-DD)

Examples:

# Download current data
barangay cache download

# Download specific historical date
barangay cache download --date "2025-07-08"

Batch

barangay batch batch-search

Batch search from file (one query per line).

barangay batch batch-search queries.txt --limit 5 --output results.json

Options:

Parameter	Type	Default	Required	Description
--limit, -l	int	5	No	Maximum number of results per query
--threshold, -t	float	60.0	No	Minimum similarity score 0-100
--as-of	str	-	No	Historical date (YYYY-MM-DD)
--level, -L	str	-	No	Post-filter results to a specific admin level
--match-hook	str	-	No	Name-levels to score against (repeatable); defaults to barangay
--output, -o	str	stdout	No	Output JSON file

Example:

# queries.txt contains one query per line
barangay batch batch-search queries.txt --limit 5 --output results.json

barangay batch validate

Validate full addresses from file (one per line). Uses the same semantics as the Python validate() function (high threshold, full address match).

barangay batch validate addresses.txt

Options:

Parameter	Type	Default	Required	Description
--as-of	str	-	No	Historical date (YYYY-MM-DD)
--threshold, -t	float	95.0	No	Minimum score for a valid match (0-100)

Output columns: Input, Valid, Match, rphicmsgb, Score.

Example:

# addresses.txt contains one full address per line, e.g.
# Tongmageng, Sitangkai, Tawi-Tawi
barangay batch validate addresses.txt

Plugins

barangay plugins list

List available plugins with their status.

barangay plugins list

Output: Table with columns: Name, Status (enabled/disabled), Description.

barangay plugins info

Show details for a specific plugin.

barangay plugins info psgc-aux-data

Output: Table with columns: Property, Value (name, enabled, description, version, format, repository).

Raises an error if the plugin name is not found.

Help

barangay --help
barangay search --help
barangay export --help
barangay info --help
barangay history --help
barangay cache --help
barangay batch --help
barangay plugins --help

See also

• Python API reference — the programmatic equivalent of these commands
• Configuration — cache dir, plugin dirs, env vars
• Geocode batch files how-to — batch commands in context