Plugin CLI Reference

Use plugins from the barangay command line: the –plugin flag enriches search and export output with supplementary PSGC data fields.
Author

bendlikeabamboo

Plugins integrate directly into the barangay search and barangay export CLI commands via the --plugin flag.

--plugin Flag

The --plugin flag is repeatable — pass it once per plugin you want to enable:

barangay search "Tondo" --plugin psgc-aux-data --plugin sample_elevation

When --plugin is used, the specified plugins are enabled on top of whatever the config files say. You do not need to edit plugins.yaml to use a plugin on the CLI.

Warning

Only one array plugin can be active at a time. Scalar plugins have no limit.

barangay search with Plugins

JSON output

barangay search "City of Lapu-Lapu" --plugin psgc-aux-data --format json --limit 1
[
  {
    "name": "Lapu-lapu",
    "type": "barangay",
    "psgc_id": "0401010008",
    "parent_psgc_id": "0401010000",
    "nicknames": null,
    "region": "Region IV-A (CALABARZON)",
    "province": "Batangas",
    "highly_urbanized_city": null,
    "independent_component_city": null,
    "component_city": null,
    "municipality": "Ibaan",
    "submunicipality": null,
    "special_geographic_area": null,
    "barangay": "Lapu-lapu",
    "rphicmsgb": "rp000m00b",
    "score": 100.0,
    "match_type": "barangay",
    "psgc_aux_data.correspondence_code": "0041010008",
    "psgc_aux_data.old_names": null,
    "psgc_aux_data.city_class": null,
    "psgc_aux_data.income_classification": null,
    "psgc_aux_data.urban_rural": "R",
    "psgc_aux_data.population": 2187,
    "psgc_aux_data.status": null
  }
]

The psgc_aux_data.* fields are injected by the plugin. Fields that are not applicable for a given record (e.g., city_class on a barangay) appear as null.

Table output

barangay search "Tondo" --plugin psgc-aux-data --format table --limit 5 --threshold 50
                                                                                             Search Results for 'Tondo'                                                                                             
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Region                      ┃ Province    ┃ Component City ┃ Municipality ┃ Barangay ┃ rphicmsgb ┃ PSGC ID    ┃ Score ┃ psgc_aux_data.correspondence_code ┃ psgc_aux_data.urban_rural ┃ psgc_aux_data.population ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Region III (Central Luzon)  │ Zambales    │                │ Cabangan     │ Tondo    │ rp000m00b │ 0307102025 │ 100.0 │ 0037102025                        │ R                         │ 1337                     │
│ Region I (Ilocos Region)    │ Pangasinan  │                │ Anda         │ Tondol   │ rp000m00b │ 0105505020 │ 90.9  │ 0015505020                        │ R                         │ 3532                     │
│ Region VI (Western Visayas) │ Aklan       │                │ Tangalan     │ Tondog   │ rp000m00b │ 0600417014 │ 90.9  │ 0060417014                        │ R                         │ 2178                     │
│ Region III (Central Luzon)  │ Nueva Ecija │ San Jose City  │              │ Tondod   │ rp00c000b │ 0304926038 │ 90.9  │ 0034926038                        │ R                         │ 3633                     │
│ Region V (Bicol Region)     │ Sorsogon    │                │ Donsol       │ Tongdol  │ rp000m00b │ 0506207047 │ 83.3  │ 0056207047                        │ R                         │ 589                      │
└─────────────────────────────┴─────────────┴────────────────┴──────────────┴──────────┴───────────┴────────────┴───────┴───────────────────────────────────┴───────────────────────────┴──────────────────────────┘

Plugin columns are automatically appended to the table. The columns shown are: psgc_aux_data.correspondence_code, psgc_aux_data.urban_rural, psgc_aux_data.population. Columns that are blank for every result (e.g., city_class, old_names) are omitted automatically.

Note

Only scalar plugins are supported with barangay search. Array plugins (like sample_schools) are ignored in search results.

barangay export with Plugins

Plugins are only supported with --model flat. Using --plugin with --model extended raises an error:

barangay export --model extended --plugin psgc-aux-data
Error: Plugins are only supported with --model flat

JSON export

barangay export --model flat --plugin psgc-aux-data --format json --output enriched.json

Each record includes plugin fields directly:

{
  "name": "City of Lapu-Lapu",
  "type": "highly_urbanized_city",
  "psgc_id": "0731100000",
  "parent_psgc_id": "0700000000",
  "nicknames": null,
  "psgc_aux_data.correspondence_code": "0072226000",
  "psgc_aux_data.old_names": "Opon",
  "psgc_aux_data.city_class": "HUC",
  "psgc_aux_data.income_classification": "1st",
  "psgc_aux_data.urban_rural": null,
  "psgc_aux_data.population": 497813,
  "psgc_aux_data.status": null
}

CSV export

barangay export --model flat --plugin psgc-aux-data --format csv --output enriched.csv

CSV header:

name,type,psgc_id,parent_psgc_id,nicknames,psgc_aux_data.correspondence_code,psgc_aux_data.old_names,psgc_aux_data.city_class,psgc_aux_data.income_classification,psgc_aux_data.urban_rural,psgc_aux_data.population,psgc_aux_data.status
Bangsamoro Autonomous Region In Muslim Mindanao (BARMM),region,1900000000,0000000000,,0150000000,,,,,4545486,

Historical plugin data

The psgc-aux-data plugin is time-aware — it provides snapshots matching PSGC release dates. Use --as-of to fetch the supplementary data that was current at that date:

barangay export --model flat --plugin psgc-aux-data --format json --as-of "2025-08-29" --output enriched_2025.json

Output (first record):

{
  "name": "Bangsamoro Autonomous Region In Muslim Mindanao (BARMM)",
  "type": "region",
  "psgc_id": "1900000000",
  "parent_psgc_id": "0000000000",
  "nicknames": null,
  "psgc_aux_data.correspondence_code": "0150000000",
  "psgc_aux_data.old_names": null,
  "psgc_aux_data.city_class": null,
  "psgc_aux_data.income_classification": null,
  "psgc_aux_data.urban_rural": null,
  "psgc_aux_data.population": 4545486,
  "psgc_aux_data.status": null
}

Multiple plugins

Enable multiple plugins by repeating the --plugin flag:

barangay export --model flat --plugin sample_elevation --plugin psgc-aux-data --format json --output multi.json

Records contain fields from both plugins:

{
  "name": "National Capital Region (NCR)",
  "type": "region",
  "psgc_id": "1300000000",
  "parent_psgc_id": "0000000000",
  "nicknames": null,
  "sample_elevation.elevation_m": "16",
  "sample_elevation.terrain": "lowland",
  "psgc_aux_data.correspondence_code": "0130000000",
  "psgc_aux_data.old_names": null,
  "psgc_aux_data.city_class": null,
  "psgc_aux_data.income_classification": null,
  "psgc_aux_data.urban_rural": null,
  "psgc_aux_data.population": 14001751,
  "psgc_aux_data.status": null
}

CLI Options Summary

Command --plugin Support Notes
barangay search Yes (scalar only) Enriches search results inline
barangay export --model flat Yes (scalar + array) Full enrichment, supports cross-join for arrays
barangay export --model extended No Raises error
barangay history search-history No Not supported
barangay history export-history No Not supported

See also