Skip to content

Portolan CLI

Cloud-native geospatial data catalogs, simplified

Portolan enables organizations to share geospatial data in a low-cost, accessible, sovereign, and reliable way. Built on cloud-native geospatial formats, a Portolan catalog is as interactive as any geospatial portal—but faster, more scalable, and much cheaper to run.

This CLI converts data to cloud-native formats (GeoParquet, COG), generates rich STAC metadata, and syncs to any object storage—no servers required.

Get Started View on GitHub

Why Portolan?

  • Scalable

    Cloud object storage that scales to petabytes

  • Open

    100% open source, open formats (GeoParquet, COG)

  • AI-Ready

    STAC metadata enables semantic search and LLM integration

  • Cheap

    Pay only for storage + egress — no servers to run

  • Sovereign

    Host anywhere (AWS, GCS, Azure, MinIO, Cloudflare R2)

  • Breaks the GIS silo

    Query with DuckDB, Snowflake, BigQuery, Databricks, Pandas — not just GIS tools

What It Does

  • Convert

    Transform vector and raster data to cloud-native formats (GeoParquet, COG)

  • Catalog

    Generate STAC catalogs with rich metadata, thumbnails, and MapLibre styles

  • Version

    Track items with checksums and full history

  • Sync

    Push to S3, GCS, Azure, or any S3-compatible storage

Installation

# Recommended: uv (fast, isolated, project-aware)
uv tool install portolan-cli

# Alternative: pipx (isolated environment)
# pipx install portolan-cli

# Alternative: pip (global/user site-packages, may conflict)
# pip install portolan-cli

For Development

git clone https://github.com/portolan-sdi/portolan-cli.git
cd portolan-cli
uv sync --all-extras
uv run portolan --help

See the Contributing Guide for full development setup.

Quick Start

# Initialize a catalog
portolan init

# Add files (creates collections from directories)
portolan add demographics/

# Validate and convert to cloud-native formats
portolan check --fix

# notest - requires S3 credentials
# Push to remote storage
portolan push s3://my-bucket/catalog --collection demographics

# Later: pull updates from remote
portolan pull s3://my-bucket/catalog -c demographics

# Or sync everything (pull → init → scan → check → push)
portolan sync s3://my-bucket/catalog -c demographics

All Commands

portolan init                               # Initialize catalog
portolan scan <path>                        # Scan for issues (--fix for filenames)
portolan add <path>                         # Track files
portolan rm <path>                          # Untrack files (--keep to preserve data)
portolan check                              # Validate catalog (metadata + geo-assets)
portolan check --fix                        # Convert to cloud-native + update metadata
portolan list                               # List tracked files
portolan info <path>                        # Show file/collection info
portolan push <remote>                      # Push to remote storage
portolan pull <remote>                      # Pull from remote storage
portolan sync <remote>                      # Full roundtrip sync
portolan clone <remote> <path>              # Clone remote catalog
portolan config <set|get|list|unset>        # Manage configuration
portolan metadata init                      # Create metadata.yaml template
portolan metadata validate                  # Validate required metadata fields
portolan readme                             # Generate README.md from STAC + metadata
portolan clean                              # Remove Portolan metadata

Next Steps

License: Apache 2.0 — View on GitHub