Overview

One binary, five subcommands. Everything below runs the same way: as terraserve <command> [flags], or inside Docker as docker run … terraserve <command> [flags] (mount your data at /data, exactly as in the quick start).

Every command prints its own flags with --help: terraserve build-pmtiles --help. The examples here use bare paths for readability; prefix them with /data/ when you run in a container.

serve

The live server: it publishes WMS, TMS, vector tiles and the built-in viewers. This is the command you run in production, and it has the most flags by far, data and styling, network, caching, vector tuning, multi-layer YAML. Its full reference lives on the Docs page. The shape is:

# one raster, as WMS + tiles
terraserve serve --cog ortho.cog.tif --style rgb.json \
  --host 0.0.0.0 --port 8080

# one vector layer (needs a style)
terraserve serve --vector roads.fgb --vec-style roads.style.json \
  --name roads --host 0.0.0.0 --port 8080

# many layers from a config
terraserve serve --config layers.yaml --host 0.0.0.0 --port 8080

The flags that matter for every deployment, --host 0.0.0.0 in a container, --public-url behind a proxy, --max-inflight as the memory ceiling, are covered with their pitfalls on the Docs.

render

The engine core with no server around it: read one window of a COG, warp and resample it into a grid, style it, write a PNG. It is the single-shot version of what serve does per WMS request, useful for a one-off image, a thumbnail, or a quick correctness check.

terraserve render \
  --cog cascais.cog.deflate.tif \
  --bbox -9.45,38.68,-9.38,38.72 --crs EPSG:4326 \
  --width 512 --height 512 \
  --resample bilinear \
  --style rgb.json \
  --out cascais.png

build-pmtiles

Drawing vector tiles live is decode-bound: at low zoom a single tile has to read and generalize a large slice of the data, and that can take seconds. build-pmtiles pays that cost once, offline, into a static .pmtiles archive. Serving from the archive is then a byte-range read (milliseconds), not a render. This is exactly what the live demos precompute.

1. Bake the pyramid.

terraserve build-pmtiles \
  --vector roads.fgb \
  --vec-style roads.style.json \
  --name roads \
  --min-zoom 0 --max-zoom 14 \
  --out roads.pmtiles

2. Serve it. Point serve at the archive with --pmtiles; keep --vector pointed at the source so a zoom outside the baked range still falls through to a live draw.

terraserve serve \
  --vector roads.fgb --vec-style roads.style.json --name roads \
  --pmtiles roads.pmtiles \
  --host 0.0.0.0 --port 8080

build-topology

A diagnostic, not a renderer. It loads a polygon coverage (a GeoPackage, FlatGeoBuf or GeoJSON), snaps and builds its shared-border topology (the arcs that neighbouring polygons have in common), and prints a report. Nothing is served or stored. Use it to check a coverage is clean before you turn on serve --topology-simplify, which builds this same structure at startup to smooth every shared border gap-free (that serve-time build is GeoPackage-only).

terraserve build-topology \
  --vector coverage.gpkg \
  --snap-tolerance 0.01 \
  --verify

The report lists the feature, ring, arc and junction counts, how many arcs are shared versus on the outer boundary, the vertex count before and after snapping, any degenerate or non-finite geometry it dropped, and the total area delta from snapping. With --verify it also round-trips the topology back to polygons and reports how many features differ: 0 / N means the topology reproduces the input exactly.

wms-handle

Answers one WMS request and writes the result to stdout, then exits, no server, no port. It handles GetMap (a PNG), GetCapabilities and exceptions (XML), for both WMS 1.1.1 and 1.3.0 including the EPSG:4326 axis flip. Handy for scripting a single render or sanity-checking WMS output in CI without binding a socket. Single COG only (no --config or --vector).

# capabilities document to a file
terraserve wms-handle --cog ortho.cog.tif --style rgb.json \
  --query 'SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities' \
  > capabilities.xml

Swap REQUEST=GetMap (with LAYERS, CRS, BBOX, WIDTH, HEIGHT, FORMAT=image/png) and redirect to a .png to get a rendered map the same way.

Full serve reference on the Docs ->