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

Two traps when baking. Set the same TERRASERVE_FGB_MAX_QUERY_FEATURES (or _PG_) the server uses: a low-zoom tile can match every feature in the file, and past the default cap of 500,000 the bake silently truncates, blanking whole regions. The bake log says capping decode when it happens; zero of those is the pass condition. And a complete low-zoom vector tile of a dense layer is enormous: one z6 tile of an 842k-polygon land-cover map held 510,000 polygons, and a few views of tiles like that took a browser to 4 GB. Keep the per-tile cap below about z9, and let a png archive underneath show every feature instead.

pmtiles-recompress

Since 0.3.4. Changes how an existing vector archive stores its tiles, without re-baking it. A bake re-reads the source and re-runs every gate and band, which for a database layer can take hours and can change the tiles. This command never touches the source: it decompresses each stored tile with the archive's own encoding, compresses it again with the new one (in parallel), copies the header and metadata, and then checks every addressed tile decodes to exactly the same bytes before reporting success. Measured on the live demos, gzip to zstd saved 4-19 % depending on the archive: the most on few large tiles (vida buildings -13.8 %), the least on many small ones (a 922 MB land-cover archive -3.7 %).

terraserve pmtiles-recompress \
  --in buildings.pmtiles --out buildings.zstd.pmtiles --tile-compression zstd
# pmtiles-recompress: buildings.pmtiles -> buildings.zstd.pmtiles (zstd) · addressed 8048 · ... -13.8% · 21.6s
# verified: 8048 addressed tiles decode identically, same ids, metadata and bounds

Point serve --pmtiles at the new file; the server reads gzip, brotli and zstd archives alike and answers each browser in an encoding it accepts. Two limits: a write-through --pmtiles-cache needs a gzip base archive, and the pmtiles tool will not merge archives of different compressions, so convert every part of a banded archive the same way.

extract

Writes a per-zoom, pre-generalized subset of a vector source as a GeoPackage. The feature selection a tile would otherwise do at render time (the size gate, the per-tile cap) is done once, on whole features, before any tile exists. Tiling the subset is then a pure spatial cut, and neighbouring tiles cannot disagree about what to keep, which is where tile seams come from. Chain the bands: extract the next shallower band from the subset you just made, not from the full table.

# a subset for zooms 5-6, on the grid the tiles will be cut on
terraserve extract \
  --vector roads.gpkg --vec-style roads.vec.json \
  --grid WebMercatorQuad --min-zoom 5 --max-zoom 6 \
  --mvt-min-feature-px 0.5 --out roads-z5-6.gpkg

# then bake that band from it
terraserve build-pmtiles --vector roads.gpkg --vec-style roads.vec.json \
  --zoom-source 5:6:roads-z5-6.gpkg --out roads.pmtiles

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.

info

Reports which PROJ this binary uses and which proj.db it actually resolved, by asking PROJ itself. --version and --help never touch PROJ, so they cannot tell you whether a reprojection will work; this can. Run it first when coordinates come out wrong, and paste it into a bug report. The standalone binary carries its own proj.db and unpacks it to a cache directory on first run; an explicit PROJ_DATA always wins.

$ terraserve info
terraserve   0.3.6
PROJ         Rel. 9.6.0, March 15th, 2025 (statically linked, vendored)
proj.db      ~/.cache/terraserve/proj-a2337534498ffcac/proj.db
             9883648 bytes
embedded     9883648 bytes, id a2337534498ffcac
PROJ_DATA    ~/.cache/terraserve/proj-a2337534498ffcac
PROJ_LIB     (unset)
search path  ~/.local/share/proj:~/.cache/terraserve/proj-a2337534498ffcac

From Python the same report is terraserve.proj_info(), a dict.

Full serve reference on the Docs ->