# Configuration

> CLI options and environment variables for controlling geolith behavior.

## Subcommands

Beyond the flat tile-pipeline flags below, geolith ships two subcommands with their own flag sets — see the [3D Terrain Pipeline guide](/builder/guides/terrain-3d):

| Subcommand | Purpose |
| --- | --- |
| `geolith terrain` | GeoTIFF DEM → Terrain-RGB PMTiles (`raster-dem`) |
| `geolith splat-tiles` | 3DGS PLY → OGC 3D Tiles (`KHR_gaussian_splatting` + SPZ) |

## 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. |
| `--reclaim-source-after-read` | `bool` | `false` | Delete 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

| 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` | `glx` | Geocoding format: `glx` (one index file for geolith search), `pg-copy`, `photon`, or `pelias`. |
| `--pg-index-flavor` | `tin` \| `gin` | `tin` | Text index in the `pg-copy` companion DDL. `tin` needs the `tin` extension (PlanetScale Postgres, Neki); `gin` runs on any Postgres. |
| `--wikimedia-importance` | `path` | — | 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](/builder/guides/geocoding-output#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](/builder/guides/geocoding-output) for the `.glx` file, document shapes and import commands, and the [Ecosystem page](/builder/architecture/ecosystem) for how each output reaches a server.

### 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):**

```bash
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:**

```bash
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:**

```bash
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:**

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

```bash
# 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
```