Builder docs

Configuration

CLI options and environment variables for controlling geolith behavior.

By · Updated

Subcommands

Beyond the flat tile-pipeline flags below, geolith ships two subcommands with their own flag sets — see the 3D Terrain Pipeline guide:

SubcommandPurpose
geolith terrainGeoTIFF DEM → Terrain-RGB PMTiles (raster-dem)
geolith splat-tiles3DGS PLY → OGC 3D Tiles (KHR_gaussian_splatting + SPZ)

CLI Options

Required Data Sources

OptionTypeDescription
--datapathPath to the Overture Maps data directory (hive-partitioned GeoParquet).
--osm-pbfpathPath to an OpenStreetMap PBF file (e.g., planet-latest.osm.pbf).
--natural-earthpathPath to Natural Earth SQLite file (spatialite blobs).
--water-polygonspathPath to water-polygons-split-3857 shapefile directory.
--land-polygonspathPath to land-polygons-split-3857 shapefile directory.

Optional Data Sources

OptionTypeDefaultDescription
--india-boundarypath—India boundary GeoJSON file for correct border rendering.

Output

OptionTypeDefaultDescription
--output / -opathrequiredOutput file path (.pmtiles or .mbtiles).
--output-formatstringtilesOutput format: tiles, valhalla, osrm, or geocoding.
--schemastringprotomapsOutput schema: protomaps, openmaptiles, or path to TOML schema.

Filtering

OptionTypeDefaultDescription
--bboxstring(entire planet)Bounding box filter as min_lon,min_lat,max_lon,max_lat in WGS84 degrees.
--max-zoomu815Maximum zoom level for tile generation (0–15).

Performance

OptionTypeDefaultDescription
--threadsusize(all cores)Number of threads for parallel processing.
--chunk-size-mbusize0 (auto)Sort buffer size per thread in MB. 0 = auto-detect based on RAM.
--tmpdirpathsystem tempDirectory for temporary sort chunk files. Use a fast SSD.
--node-storepath—Path to mmap file for OSM node coordinates (96+ GB for planet).
--node-cachebooltrueCache node store between runs (skip OSM pass 1 on re-runs).
--resumeboolfalseResume from existing sort chunks in --tmpdir, skipping Phase 1.
--reclaim-source-after-readboolfalseDelete each Overture Parquet file once its features are in the sort chunks, keeping the disk peak near the release size instead of release + chunks. Only Overture inputs are removed; re-download the release to restore.

GERS Conflation

OptionTypeDefaultDescription
--bridge-dirpath—Directory of GERS bridge Parquet files. Auto-discovered from gers-bridge/ sibling of --data if not set.
--bridge-filespath (multi)—Individual GERS bridge Parquet files (can be specified multiple times).
--no-conflateboolfalseDisable 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).

OptionDefaultValues
--buildings-sourcebothosm, overture, both
--roads-sourcebothosm, overture, both
--places-sourcebothosm, overture, both
--pois-sourceovertureosm, overture, both
--water-sourceovertureosm, overture, both
--landuse-sourceovertureosm, overture, both
--divisions-sourceovertureoverture, none
--landcover-sourceovertureoverture, none
--bathymetry-sourceovertureoverture, none

Routing Output

OptionTypeDefaultDescription
--osrm-outputpath—OSRM tar archive output path (requires --output-format osrm).
--valhalla-outputpath—Valhalla tar archive output path (requires --output-format valhalla).

Geocoding Output

OptionTypeDefaultDescription
--geocoding-outputpath—Geocoding data output path (requires --output-format geocoding).
--geocoding-formatstringglxGeocoding format: glx (one index file for geolith search), pg-copy, photon, or pelias.
--pg-index-flavortin | gintinText index in the pg-copy companion DDL. tin needs the tin extension (PlanetScale Postgres, Neki); gin runs on any Postgres.
--wikimedia-importancepath—Nominatim's wikimedia-importance.csv.gz. An OSM place with a wikidata tag takes the importance of its Wikipedia article; without the file, each place takes the default of its type. See Importance.

Reads Overture places and addresses and, with --osm-pbf, named OSM settlements, venues, and addresses (all respecting --bbox). The pelias format additionally writes Overture buildings to a <stem>-buildings.ndjson sidecar for a separate buildings index. See the Geocoding Output guide for the .glx file, document shapes and import commands, and the Ecosystem page for how each output reaches a server.

Incremental Updates

OptionTypeDefaultDescription
--incrementalboolfalseEnable incremental update mode (patch existing MBTiles).
--state-dirpath—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

VariableDescription
RUST_LOGControls 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