portolan-cli 0.4.3

A CLI tool for managing cloud-native geospatial data

---

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

# Scan a directory for issues (optional but recommended)
portolan scan demographics/

# Add all files in a directory (creates a "demographics" collection)
portolan add demographics/

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

Other common commands:

portolan check                              # Validate catalog
portolan check --fix                        # Convert to cloud-native formats
portolan rm --keep demographics/old.parquet # Untrack without deleting
# notest - requires S3 credentials
portolan pull s3://my-bucket/catalog -c demographics  # Pull from remote
# notest - requires S3 credentials
portolan sync s3://my-bucket/catalog -c demographics  # Full workflow: pull → check → push
portolan config set remote s3://my-bucket/catalog     # Save remote URL
portolan config list                        # List all config settings

Installation

Recommended: pipx (for global use)

# notest - installation command
pipx install portolan-cli

This installs portolan in an isolated environment while making the command globally available.

If you don't have pipx installed:

# notest - installation commands
python3 -m pip install --user pipx
python3 -m pipx ensurepath

Alternative: pip

# notest - installation command
pip install portolan-cli

Note: This installs into your global or user site-packages and may conflict with other packages.

For Development

Use uv for local development:

# notest - development setup
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.

Documentation

• Contributing Guide

License

Apache 2.0 — see LICENSE