Configuration

CLI Options

Required Data Sources

Option	Type	Description
`--data`	`path`	Path to the Overture Maps data directory (hive-partitioned GeoParquet).
`--osm-pbf`	`path`	Path to an OpenStreetMap PBF file (e.g., `planet-latest.osm.pbf`).
`--natural-earth`	`path`	Path to Natural Earth SQLite file (spatialite blobs).
`--water-polygons`	`path`	Path to water-polygons-split-3857 shapefile directory.
`--land-polygons`	`path`	Path to land-polygons-split-3857 shapefile directory.

Optional Data Sources

Option	Type	Default	Description
`--india-boundary`	`path`	—	India boundary GeoJSON file for correct border rendering.

Output

Option	Type	Default	Description
`--output` / `-o`	`path`	required	Output file path (`.pmtiles` or `.mbtiles`).
`--output-format`	`string`	`tiles`	Output format: `tiles`, `valhalla`, `osrm`, or `geocoding`.
`--schema`	`string`	`protomaps`	Output schema: `protomaps`, `openmaptiles`, or path to TOML schema.

Filtering

Option	Type	Default	Description
`--bbox`	`string`	(entire planet)	Bounding box filter as `min_lon,min_lat,max_lon,max_lat` in WGS84 degrees.
`--max-zoom`	`u8`	`15`	Maximum zoom level for tile generation (0–15).

Performance

Option	Type	Default	Description
`--threads`	`usize`	(all cores)	Number of threads for parallel processing.
`--chunk-size-mb`	`usize`	`0` (auto)	Sort buffer size per thread in MB. 0 = auto-detect based on RAM.
`--tmpdir`	`path`	system temp	Directory for temporary sort chunk files. Use a fast SSD.
`--node-store`	`path`	—	Path to mmap file for OSM node coordinates (96+ GB for planet).
`--node-cache`	`bool`	`true`	Cache node store between runs (skip OSM pass 1 on re-runs).
`--resume`	`bool`	`false`	Resume from existing sort chunks in `--tmpdir`, skipping Phase 1.

GERS Conflation

Option	Type	Default	Description
`--bridge-dir`	`path`	—	Directory of GERS bridge Parquet files. Auto-discovered from `gers-bridge/` sibling of `--data` if not set.
`--bridge-files`	`path` (multi)	—	Individual GERS bridge Parquet files (can be specified multiple times).
`--no-conflate`	`bool`	`false`	Disable GERS conflation even when bridge files are found.

Layer Source Selection

Control which data source is used per layer. Values: "osm", "overture", or "both" (unless noted).

Option	Default	Values
`--buildings-source`	`both`	`osm`, `overture`, `both`
`--roads-source`	`both`	`osm`, `overture`, `both`
`--places-source`	`both`	`osm`, `overture`, `both`
`--pois-source`	`overture`	`osm`, `overture`, `both`
`--water-source`	`overture`	`osm`, `overture`, `both`
`--landuse-source`	`overture`	`osm`, `overture`, `both`
`--divisions-source`	`overture`	`overture`, `none`
`--landcover-source`	`overture`	`overture`, `none`
`--bathymetry-source`	`overture`	`overture`, `none`

Routing Output

Option	Type	Default	Description
`--osrm-output`	`path`	—	OSRM tar archive output path (requires `--output-format osrm`).
`--valhalla-output`	`path`	—	Valhalla tar archive output path (requires `--output-format valhalla`).

Geocoding Output

Option	Type	Default	Description
`--geocoding-output`	`path`	—	Geocoding data output path (requires `--output-format geocoding`).
`--geocoding-format`	`string`	`pg-copy`	Geocoding format: `pg-copy`, `photon`, or `pelias`.

Incremental Updates

Option	Type	Default	Description
`--incremental`	`bool`	`false`	Enable incremental update mode (patch existing MBTiles).
`--state-dir`	`path`	—	Persistent state directory for incremental processing.

Usage Examples

Full planet build (6 sources, auto GERS conflation):

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --india-boundary ./data/india-boundary.geojson \
  --output ./data/planet-vector.pmtiles \
  --max-zoom 15 \
  --threads 10 \
  --tmpdir ./data/tmp \
  --node-store ./data/node.store

Regional extract with bounding box:

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/india.pmtiles \
  --bbox 68.0,6.5,97.5,37.2 \
  --max-zoom 15

Explicit GERS bridge directory:

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles \
  --bridge-dir ./data/gers-bridge

Disable conflation:

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles \
  --no-conflate

Environment Variables

Variable	Description
`RUST_LOG`	Controls log verbosity. Set to `info`, `debug`, or `trace` for increasing detail.

# Show progress and timing information
RUST_LOG=info geolith --data ./data/overture --osm-pbf ./data/planet.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons --output planet.pmtiles

# Trace a specific module
RUST_LOG=geolith::pipeline=trace geolith --data ./data/overture --osm-pbf ./data/planet.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons --output planet.pmtiles