Metadata-Version: 2.4
Name: portolan-cli
Version: 0.4.1
Summary: A CLI tool for managing cloud-native geospatial data
Project-URL: Homepage, https://github.com/portolan-sdi/portolan-cli
Project-URL: Bug Tracker, https://github.com/portolan-sdi/portolan-cli/issues
Project-URL: Documentation, https://github.com/portolan-sdi/portolan-cli#readme
Project-URL: Source, https://github.com/portolan-sdi/portolan-cli
Author-email: Nissim Lebovits <nlebovits@pm.me>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cloud-native,geospatial,gis,io
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: click>=8.3.1
Requires-Dist: geoparquet-io>=0.3.0
Requires-Dist: obstore>=0.8.2
Requires-Dist: pyarrow<22.0.0,>=12.0.0
Requires-Dist: pystac>=1.10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rio-cogeo>=5.0.0
Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: bandit>=1.9.3; extra == 'dev'
Requires-Dist: codespell>=2.4.1; extra == 'dev'
Requires-Dist: commitizen>=4.13.4; extra == 'dev'
Requires-Dist: gitingest>=0.1.0; extra == 'dev'
Requires-Dist: hypothesis>=6.151.5; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: mutmut>=3.4.0; extra == 'dev'
Requires-Dist: mypy>=1.19.1; extra == 'dev'
Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
Requires-Dist: pytest-benchmark>=5.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: radon>=6.0.1; extra == 'dev'
Requires-Dist: ruff>=0.14.11; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: vulture>=2.14; extra == 'dev'
Requires-Dist: xenon>=0.9.3; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-click>=0.8.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.7.1; extra == 'docs'
Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'docs'
Description-Content-Type: text/markdown

<div align="center">
  <img src="docs/assets/images/cover.png" alt="Portolan" width="600"/>
</div>

<div align="center">

[![CI](https://github.com/portolan-sdi/portolan-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/portolan-sdi/portolan-cli/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/portolan-sdi/portolan-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/portolan-sdi/portolan-cli)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![PyPI version](https://badge.fury.io/py/portolan-cli.svg)](https://badge.fury.io/py/portolan-cli)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

</div>

---

<!-- --8<-- [start:intro] -->
Portolan enables organizations to share geospatial data in a low-cost, accessible, sovereign, and reliable way. Built on [cloud-native geospatial](https://cloudnativegeo.org) 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.
<!-- --8<-- [end:intro] -->

<!-- --8<-- [start:quickstart] -->
## Quick Start

```bash
# 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:

```bash
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
```
<!-- --8<-- [end:quickstart] -->

<!-- --8<-- [start:installation] -->
## Installation

### Recommended: pipx (for global use)

```bash
# 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:
```bash
# notest - installation commands
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```

### Alternative: pip

```bash
# 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](https://github.com/astral-sh/uv) for local development:

```bash
# notest - development setup
git clone https://github.com/portolan-sdi/portolan-cli.git
cd portolan-cli
uv sync --all-extras
uv run portolan --help
```
<!-- --8<-- [end:installation] -->

See [Contributing Guide](docs/contributing.md) for full development setup.

## Documentation

- [Contributing Guide](docs/contributing.md)

## License

Apache 2.0 — see [LICENSE](LICENSE)
