---

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.

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 add-external <url>                 # Reference a remote dataset in place (no download/convert)
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

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 Contributing Guide for full development setup.

License

Apache 2.0 — see LICENSE