Portolan CLI

Portolan is a specification for cloud-native geospatial data catalogs, built on STAC. portolan-cli implements it. The portolan-spec repository is ground truth. Read specs/portolan/core.md and specs/portolan/formats.md there when a requirement is in doubt. The CLI converts data to GeoParquet, COG, and PMTiles. It then writes the STAC tree and validates it. portolan push syncs the result to object storage. There is no server. A catalog is static files.

This skill tracks the PyPI release named in pins.toml. Run portolan <command> --help for the options of any command. The help text is the reference. This skill only says which command to reach for and in what order.

Installation

uv tool install portolan-cli
portolan --version

Files the CLI writes

portolan init writes a root catalog.json, AGENTS.md, README.md, versions.json, and .portolan/config.yaml plus .portolan/metadata.yaml. The root declares the v0.2.0 schema URI in stac_extensions. That URI is the only signal of the spec version (PORTO-CORE-006). Its links are root, agents, and describedby. It writes no self link. Add an absolute self link at publish time (PORTO-CORE-081).

portolan add <dir> turns a directory into a collection. For one GeoParquet file, with --pmtiles, it writes:

demo/
├── collection.json
├── AGENTS.md
├── README.md
├── versions.json
├── data.parquet          asset role: data
├── data.pmtiles          asset role: visual, plus a rel: pmtiles link
├── data.thumb.jpg        asset role: thumbnail
└── styles/default.json   asset roles: style, default

Without --pmtiles there is no PMTiles file and no styles/ directory, so a vector collection has no render path (PORTO-CORE-065). Pass --pmtiles for vector data.

AGENTS.md and README.md beside every catalog.json and collection.json are spec requirements (PORTO-CORE-005). versions.json is a CLI artifact that tracks sync state and checksums. It is not part of the spec. Dataset versioning uses the STAC version extension (PORTO-CORE-008).

One file is a collection-level asset with no item (PORTO-CORE-017). A partitioned collection uses the partition extension and its partition:glob (PORTO-FMT-017). Items for opaque partition schemes are not created (PORTO-FMT-022). Many raster scenes in one collection get one item each (PORTO-CORE-071), and portolan stac-geoparquet writes the items.parquet mirror for it.

Structural links stay relative, so the catalog is portable.

Which command

Facts that trip agents:

• init needs --license whenever --auto or --json is passed. Without them it prompts.
• sync requires -c. It runs on one collection, never catalog-wide.
• check reads remote assets over range requests in its data pass. Pass --data-scope local to read only assets inside the tree, or --no-data to skip the pass.
• check --fix removes portolan:datetime_provisional from items. The item then has no provisional marker.
• add takes --pmtiles, --force-pmtiles, --thumbnails, --force-thumbnails, --stac-geoparquet, --item-id, --datetime, --reconvert, and --force. --force-pmtiles implies --pmtiles.
• push --workers is the parallelism across collections. --concurrency is the upload parallelism within one, default 8. Neither has a cap.
• The root group takes --format json. Most subcommands take --json. partition accepts no JSON flag.
• check calls the pinned rashid. Where the two disagree, the spec decides, and the disagreement is a bug to report.

Workflows

Publish a new catalog:

portolan init --auto --license CC-BY-4.0 --title "My Geospatial Data"
portolan scan /data/geospatial
portolan add demographics/ --pmtiles
portolan check
portolan push s3://mybucket/my-catalog -c demographics

Update one collection end to end:

portolan sync s3://mybucket/my-catalog -c demographics --fix

Read the JSON envelope when a script runs the CLI:

portolan --format json check
portolan scan . --json

The envelope is {"success": true, "command": "...", "data": {...}, "errors": []}.

Troubleshooting