pmtiles CLI ​

CLI Overview ​

Remote archives ​

Remote buckets are specified in the CLI via URLS. Commands are similar to:

pmtiles [COMMAND] [KEY] --bucket=[PROTOCOL]://[BUCKET_NAME]

pmtiles [COMMAND] [KEY] --bucket=[PROTOCOL]://[BUCKET_NAME]

The bucket URL can contain query parameters like:

• endpoint: If not using AWS, an S3-compatible HTTPS endpoint.
• region: a provider-specific region string, such as us-west-2 for AWS, and auto for all Cloudflare regions.

Example of reading from a private Cloudflare R2 bucket:

Since this command uses URL characters like ? and &, those must be escaped by a backslash \.

export AWS_ACCESS_KEY_ID=MY_KEY
export AWS_SECRET_ACCESS_KEY=MY_SECRET
pmtiles show NAME.pmtiles --bucket=s3://R2_BUCKET_NAME\?endpoint=https://R2_ACCOUNT_ID.r2.cloudflarestorage.com\&region=auto

export AWS_ACCESS_KEY_ID=MY_KEY
export AWS_SECRET_ACCESS_KEY=MY_SECRET
pmtiles show NAME.pmtiles --bucket=s3://R2_BUCKET_NAME\?endpoint=https://R2_ACCOUNT_ID.r2.cloudflarestorage.com\&region=auto

Note that S3-compatible storage servers like Minio, Ceph and SeaweedFS may require additional URL options like s3ForcePathStyle=true.

Commands ​

show ​

pmtiles show INPUT.pmtiles

pmtiles show INPUT.pmtiles

Print an archive's header data and metadata.

tile ​

pmtiles tile INPUT.pmtiles 0 0 0

pmtiles tile INPUT.pmtiles 0 0 0

Output a single tile to stdout.

verify ​

pmtiles verify INPUT.pmtiles

pmtiles verify INPUT.pmtiles

Check that an archive is ordered correctly and has correct header information.

extract ​

pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --bbox=MIN_LON,MIN_LAT,MAX_LON,MAX_LAT
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --region=REGION.geojson

pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --bbox=MIN_LON,MIN_LAT,MAX_LON,MAX_LAT
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --region=REGION.geojson

Create a smaller archive from a larger archive. The source archive may be local or remote. The source archive must be clustered.

Options:

• --maxzoom: Extract only a subset of zoom levels. Extracting a full sub-pyramid from 0 to maxzoom is always an efficient operation that makes minimal I/O or network requests to the source archive.
• --minzoom: Extract only a partial sub-pyramid. This may require many more requests than leaving the default --minzoom=0. Because this removes overview zoom levels, it should only be used in specific situations.

serve ​

pmtiles serve .
pmtiles serve . --bucket=https://example.com
pmtiles serve / --bucket=s3://BUCKET_NAME

pmtiles serve .
pmtiles serve . --bucket=https://example.com
pmtiles serve / --bucket=s3://BUCKET_NAME

Expose Z/X/Y tile URLS, e.g. /mymap/{z}/{x}/{y}.mvt, for a directory or bucket of archives. Requests for the raw file e.g. mymap.pmtiles will not work.

A Z/X/Y URL like is directly supported by web and native clients such as MapLibre, without needing the PMTiles client library. Using pmtiles serve this way also allows serving public Z/X/Y traffic from private storage buckets.

convert ​

pmtiles convert INPUT.mbtiles OUTPUT.pmtiles

pmtiles convert INPUT.mbtiles OUTPUT.pmtiles

Convert from MBTiles.

version ​

pmtiles version

pmtiles version

Print the version of the command line tool.