scse-spatial 1.0.0__py3-none-any.whl

scse_spatial-1.0.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: scse-spatial
+Version: 1.0.0
+Summary: A registry enabling the indexing and querying of spatial data resources on other services.
+Author: Max Wolschlager
+Author-email: rxtx@ungut.at
+Requires-Python: >=3.11,<3.15
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: alembic (>=1.12.0,<2.0.0)
+Requires-Dist: dask (>=2024.0.0)
+Requires-Dist: geoalchemy2 (>=0.20.0,<0.21.0)
+Requires-Dist: geopandas (>=1.0,<2.0)
+Requires-Dist: jsonschema (>=4.26.0,<5.0.0)
+Requires-Dist: litestar (>=2.0.0,<3.0.0)
+Requires-Dist: mapbox-vector-tile (>=2,<3)
+Requires-Dist: morecantile (>=7.0.3,<8.0)
+Requires-Dist: netcdf4 (>=1.7.3,<2.0.0)
+Requires-Dist: pmtiles (>=3.7,<4)
+Requires-Dist: psycopg[binary] (>=3.1.12,<4.0.0)
+Requires-Dist: pydantic (>=2.4.2,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.0.3,<3.0.0)
+Requires-Dist: pyproj (>=3.1,<4.0)
+Requires-Dist: pystac[validation] (>=1.12,<1.13)
+Requires-Dist: rasterio (>=1.4.3,<2.0.0)
+Requires-Dist: rich (>=13.9.4,<14.0.0)
+Requires-Dist: rioxarray (>=0.19,<1.0)
+Requires-Dist: s3fs (>=2024.10.0,<2027.0.0)
+Requires-Dist: scse-toolkit (>=2,<3)
+Requires-Dist: sqlalchemy (>=2.0.21,<3)
+Requires-Dist: tippecanoe (>=2.45)
+Requires-Dist: titiler-core (>=2.0,<3.0)
+Requires-Dist: titiler-xarray[fs] (>=2.0,<3.0)
+Requires-Dist: typer (>=0.24.1,<0.25.0)
+Requires-Dist: uvicorn (>=0.52.1,<0.53.0)
+Requires-Dist: xarray (>=2025.1.0,<2026)
+Requires-Dist: xxhash (>=3.4.1,<4.0.0)
+Requires-Dist: zarr (>=3.0.0,<4.0)
+Description-Content-Type: text/markdown
+
+# scse-spatial
+
+A registry that indexes and queries spatial data resources on other services.
+
+## Overview
+
+scse-spatial is the spatial data extension to a scenario services web
+application stack. It turns geodata files into fast, web-optimized resources
+and serves them to any map app.
+
+A workflow loads data. A web app reads it. This repository provides both
+sides: the ingest path and the HTTP API.
+
+### Feeding it
+
+Workflows push data in with the CLI or a few lines of Python. The `Spatial`
+object connects to a PostGIS database and to object storage. It exposes
+services for rasters, features, and a STAC catalog.
+
+```python
+with Spatial("<platform>", settings=Settings()) as spatial:
+    spatial.rasters.sync_hierarchy(
+        "emissions",
+        [path],
+        parameters_class=EmissionParameters,
+        metadata_class=EmissionMetadata,
+        extract_meta=extract_em_meta,
+    )
+    spatial.stac.export_catalog()
+```
+
+The platform converts each source file into optimized formats, uploads them,
+and indexes them. A re-run skips files whose content did not change.
+
+Workflows live in their own repositories. See `WORKFLOWS.md` for more information.
+
+### Connecting to a platform
+
+In multi-tenant deployments the connection details come from the manager
+API. Staff log in with their user account once; the credentials are cached
+locally and used in place of the shared service secret.
+
+```bash
+spatial login          # prompts for username and password, caches them
+spatial whoami         # show the identity the CLI would use
+spatial platforms      # list the platforms you can access
+```
+
+The manager DSN's secret material stays in the local environment through
+`{env:...}` placeholders. Imports are attributed to the logged-in user.
+
+### HTTP API
+
+Web apps can read data over HTTP. A Litestar server lists hierarchies and
+layers, renders map tiles through TiTiler, and streams vector tiles and
+GeoJSON from object storage.
+
+```bash
+curl -X PATCH http://<scse-spatial>/v1/{platform}/rasters/ \
+     -H "Content-Type: application/json" \
+     -d '{"hierarchy_id": 3, "parameters__contains": {"sector": "power"}}'
+```
+
+Point an scse-app at the `/v1` or `/titiler` endpoints, or open `/docs` and
+`/titiler/docs` for interactive API docs. See `HTTP_API.md` for more information.
+
+## Development Setup
+
+```bash
+# Install Poetry, minimum version >=1.2 required
+pipx install poetry
+
+# You may have to reinitialize your shell at this point.
+source ~/.bashrc
+
+# Activate in-project virtualenvs
+poetry config virtualenvs.in-project true
+
+# Add dynamic versioning plugin
+poetry self add "poetry-dynamic-versioning[plugin]"
+
+# Install dependencies
+# (using "--with dev" if dev dependencies should be installed as well)
+poetry install --with dev
+
+# Activate virtual environment
+poetry shell
+
+# Copy the template environment configuration
+cp template.env .env
+
+```
+

scse_spatial-1.0.0.dist-info/RECORD

@@ -0,0 +1,71 @@
+spatial/__init__.py,sha256=O5fnfu4pycUsZ2OxD75O44Z2oYe7ypc-ErLOzxo3-iE,347
+spatial/__main__.py,sha256=XkhyIe8pfOPor5k9qmd3xaLk0NX9k84P8552WluOVgs,66
+spatial/_version.py,sha256=cRA43y3Jnp27uBqDtCORV6hlW2Ee4vFj6IKmlZcGaq0,52
+spatial/cli/__init__.py,sha256=MoAVw81l00fM4iz5H23MDw8RTglGHE-lI6AZNaA7Fyc,441
+spatial/cli/alembic.py,sha256=8_kD3luu-fZDj_-xE45m2B8mdfGtnoOmsGYUisK98WU,2580
+spatial/cli/imports.py,sha256=8gP3XSnxxnPBavsabl_dwcZQ-uBG3oVPqzwYJ-GlltA,2908
+spatial/cli/manager.py,sha256=esKbUoVHBECB5FPq74gJnJEP4h_xEcRDrQH-Y4_aWdk,5220
+spatial/cli/server.py,sha256=Pds1WNRmZz4ZATMZdmHjzxhRkL9RrUxca1ob101byWw,452
+spatial/cli/workflow.py,sha256=vaQTE9Mz07GKUV0Z8aFIV97p2TI-zOwEoydBXrFwV8U,11766
+spatial/conf/__init__.py,sha256=l8BKzRD687hZpeXRDt-cYkNDMB6eiyL6a1vHPmIQPN0,132
+spatial/conf/credentials.py,sha256=I92EOIJ9tbrCbxOdIoOmnGk5HtEx4sO7U5z8sRO1TW4,2312
+spatial/conf/logging.json,sha256=OnlLx791TO87yj-n2Mh1fZp0vDeprgsPEpKg_bRZAfo,821
+spatial/conf/platforms.py,sha256=3ctns1jl1jHZSGA6QXOclUyD1b0rWv6Fv9dx90eShuA,3052
+spatial/conf/settings.py,sha256=feraDkHM_qvs503DnkMz7DustS4GR_KyKlg6pzMzqHc,14845
+spatial/data/base/exceptions.py,sha256=mLE5tadlyFXu2LMqJEkUxKRhBaifseze3b8Rtsbxq54,913
+spatial/data/base/filters.py,sha256=md1XJ-jdrKPBSEEZpTMqaZeeFpm5qOBcbRNiHXyKAv8,2052
+spatial/data/base/hierarchy.py,sha256=8kPwVS0n9vQZwwtg0v99RLHq6Sdrd9OdB8LjvAu9Ue4,10584
+spatial/data/base/pagination.py,sha256=dDFQX1eu2DuPp7mTd8rV_2grtIxl1UnBSvYgYAIEPO0,2300
+spatial/data/base/service.py,sha256=WU3u6jR7Kax4GiTETHUszOQwhSgZeyIoQt99uK0Vo9o,5889
+spatial/data/features/__init__.py,sha256=d8kqJ2X5CVaDU6oKUCvmaOWRPJp3bjcgqHZ2fxtet5Y,89
+spatial/data/features/controller.py,sha256=P_r9HXSrvwwoT0jFbsGQbrK0oYqyHLyQtrjfP3n4u4g,3806
+spatial/data/features/db.py,sha256=NRtHKg5jbvqUo_cQVw1Umrmdp3a_eN2oGcFy78MNUKI,4589
+spatial/data/features/dto.py,sha256=A7ka9olxocceIBy9UgI1kBI0Xw8WhoxVwGUtsxY7rYk,2086
+spatial/data/features/service.py,sha256=-KsBI3025Ivt2syvGkWmbU6o63HP9ZC-Y1CRNZUQnZw,26852
+spatial/data/features/tiling.py,sha256=4Jcgfh3Q795-X7_hHo7uIO8PJWP2ixHvWnzDrRzbbOU,3397
+spatial/data/file_storage.py,sha256=GFyfKE4G2RkOCsKOzSa0IKSl_3Ak55mI299ZiKXMirU,13259
+spatial/data/hashing.py,sha256=mTLyANp2UDwP4E1hKD1h5T-sa_615OM-aEnM5WnZaDY,795
+spatial/data/manifest/__init__.py,sha256=tpnbfmyLrF6rx8PuUKWkBTLv_hmqrrt0VT2_9vAU4po,187
+spatial/data/manifest/db.py,sha256=ZeYNapN3lQM6Jh-e_uoFoblhOrr_HFXIxu6el0MsKMM,4041
+spatial/data/rasters/__init__.py,sha256=Y_KQHT2XPQ8XcwV3l2yDQXHTyqEj-Qz-sw3znYc5HwY,192
+spatial/data/rasters/controller.py,sha256=rVmyD_D7S5GcqhOYT_h4tAIXm_zl5nHDXEnIZlxlvV4,4970
+spatial/data/rasters/db.py,sha256=hhVFkn99T7qFaFLHonbTa1fpXaEg-fRinNam23svgZY,7603
+spatial/data/rasters/dto.py,sha256=JTdpX8V_UrffgsbKRF3pcaoygPKKKyGtxN2p1sZN6TQ,2882
+spatial/data/rasters/service.py,sha256=l5xASgVkkDiZc77rYX3O14g3tmkGdvD32ZGLtFzTf-c,81385
+spatial/data/rasters/tile.py,sha256=UuXL1O8pw_elU1a-xyiYvi-FI-VdUDehsy4zdBwFY7A,1265
+spatial/data/stac/__init__.py,sha256=9TOLTj8K1JqNWYij4IlDIhr6UsskgXBnlr51KQqGois,64
+spatial/data/stac/io.py,sha256=P_B8jWed7twigufVeooPQ0NjwbdeteiQhV9gi3AAa8A,2782
+spatial/data/stac/service.py,sha256=MQR8MQaM2_KsdqSgDphHp_mHTKkWm1bCs2aqgFzh1oc,13417
+spatial/db/__init__.py,sha256=Wib0RZ1o0mLdfJEshRaDhQv6LMTjG3MGDv9cxtBcnhQ,652
+spatial/db/base.py,sha256=M2b3apFLfWjRj_rB8OXpbZTUcdrfEX1ZV-dYm82OeZw,981
+spatial/db/migrations/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+spatial/db/migrations/env.py,sha256=Xwg6_Bf5rb-c161bzpyb0_FqgKlZzucB3jqiOz1VNYA,2695
+spatial/db/migrations/script.py.mako,sha256=MEqL-2qATlST9TAOeYgscMn1uy6HUS9NFvDgl93dMj8,635
+spatial/db/migrations/versions/64901b988c97_initial.py,sha256=3C8i4gRa8re2_TMXQykrKGJXGn7ur-RRbivc9iLJMPk,7979
+spatial/db/migrations/versions/7f3e2a1b9c4d_rename_url_columns_to_path.py,sha256=RGXR5LjSiisvTel_gA_2mLGAzo5EbxEvvMeh-Xg0jgg,3810
+spatial/db/migrations/versions/8a2b3c4d5e6f_store_tile_params_in_metadata.py,sha256=8_N9X3GjKjZzl_R_tnGed3pWzMORnsxZcGE-HrBa-ZI,1332
+spatial/db/migrations/versions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spatial/db/migrations/versions/a1b2c3d4e5f6_drop_raster_step_columns.py,sha256=304_GfhcbmiSDUs6fahOnbHJm_hzDpPmI0vYPMzJRm0,1037
+spatial/db/migrations/versions/b1c3d5e7f9a1_add_raster_hierarchy_projection_epsg.py,sha256=hLgbgoLzKVq6OQnG8Vxez3keYvZK12duHWuievgTFp8,896
+spatial/db/migrations/versions/c5f3a4b8d9e7_drop_zarr_variable_and_feature_crs.py,sha256=l9BFVy6JceZkzwuTWnwsntPXorgbCjZr6rXY6EFqh3E,988
+spatial/db/migrations/versions/d2e4f6a8b0c2_add_jsonb_gin_indexes.py,sha256=-dbQy0qbsdv84bdEGQ7rV29G3i9bLehi9sdujh_GWlA,1450
+spatial/db/migrations/versions/e3f5a7c9d1b2_add_actor_attribution.py,sha256=r6TIiPnxZsCWEzBcnQj5qwm6vq7jtV6pBUCrmyc8EX0,1390
+spatial/db/models.py,sha256=qYHUO1_3SNkzv7e0_lv9cOfDtOcGD_Dpvsr_9x6N_Zs,420
+spatial/projections.py,sha256=uAr0vidrwo70ktE0bUKxNITid93rzOgw1LHhfV3lEzk,9896
+spatial/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+spatial/server/__init__.py,sha256=W9gAiMQESiDlnfhcbU00PY4PL0gIun0Tb13KBlFMWEE,223
+spatial/server/algorithm.py,sha256=tkJewk_DJEep0NjHJcVWqR1EbK5V6OBrkpDczrPZNec,1810
+spatial/server/app.py,sha256=oZm3DWgfBJ9RntURG_R3DhJrOcae1jb1jZH6IiqDo64,6678
+spatial/server/data_serve.py,sha256=ZkvKsR01CXYT-gOoITKJ0Fr55ZlqdmFwzkHVf0veUTA,4486
+spatial/server/dependencies.py,sha256=z7eM94jwLqp6OShiA3NJE7NjK1Z-k6x7uRw5Coa41us,3208
+spatial/server/exceptions.py,sha256=3l_MhJhpWPmeQC5_2CgGonhIzetgb0VS3JfHDsvxsas,1483
+spatial/server/mounts.py,sha256=CcAdrWjq5x5KdQYtdLUXfsMMKeyqTf7DBT-cLets_18,2636
+spatial/server/root.py,sha256=Z3MVLzY9tN39HbhvrqtbSq1jo86Mv-XLFolKELD_Su4,2062
+spatial/server/schemas.py,sha256=EzAnUih-tkkStVL_a3UsNwzfI68UW69Msbutlyg_GS8,963
+spatial/server/stac.py,sha256=1R9kyb4zirV_Y37fpMu0b4UafXAijO1DRxdNXfQR_kA,3199
+spatial/server/titiler.py,sha256=2ZwCbiBnGSZNmYZ2K1BZ5jUDnITleO-D6vjgv0ZonLs,11820
+spatial/spatial.py,sha256=bSqEq6zC98dl4T-Aky7vEzmO9WQbwtbrGPESqsOWFwk,10047
+scse_spatial-1.0.0.dist-info/METADATA,sha256=HNT214BHTmQVQlXMFX00bCsRhFpDxOnCsLxovPZrtqI,4583
+scse_spatial-1.0.0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+scse_spatial-1.0.0.dist-info/entry_points.txt,sha256=k3HIUh-3rmsb-ExarlxTsuIt6Qc7JvQiFSWzAJtixiw,48
+scse_spatial-1.0.0.dist-info/RECORD,,

scse_spatial-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.5.0
+Root-Is-Purelib: true
+Tag: py3-none-any

scse_spatial-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+spatial=spatial.__main__:app
+

spatial/__init__.py

@@ -0,0 +1,7 @@
+from ._version import __version__ as __version__
+from ._version import __version_tuple__ as __version_tuple__
+from .spatial import Spatial as Spatial
+from .data.base.exceptions import Skip as Skip
+from .data.features import Feature as Feature
+from .data.rasters import RasterLayer as RasterLayer
+from .data.rasters import TileParams as TileParams

spatial/__main__.py

@@ -0,0 +1,4 @@
+from spatial.cli import app
+
+if __name__ == "__main__":
+    app()

spatial/_version.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.0"
+__version_tuple__ = (1, 0, 0)

spatial/cli/__init__.py

@@ -0,0 +1,19 @@
+"""Command line interface of the spatial data platform.
+
+See the CLI help for usage information:
+
+.. code:: bash
+
+    spatial --help
+    spatial server --help
+"""
+
+import typer
+from . import server, alembic, workflow, manager
+
+app = typer.Typer()
+app.add_typer(server.app, name="server")
+app.add_typer(alembic.app, name="alembic")
+app.add_typer(workflow.app)
+app.add_typer(manager.app)
+app.add_typer(manager.platforms_app, name="platforms")

spatial/cli/alembic.py

@@ -0,0 +1,85 @@
+import typer
+from toolkit.db.alembic import AlembicCli
+from typing_extensions import Annotated
+
+from spatial.conf import Settings
+from spatial.conf.platforms import (
+    resolve_dsn_env_tokens,
+    resolve_spatial_dsn,
+)
+from spatial.db import get_alembic_controller
+
+app = AlembicCli(
+    help="Manages alembic migrations on selected platforms via subcommands."
+)
+
+
+def collect_platforms(
+    settings: Settings,
+    *,
+    platform: list[str] | None,
+    manager: bool,
+) -> list[str]:
+    """Collect the DSNs of the selected command targets."""
+    candidates: list[str] = []
+    if settings.manager_url is not None and (platform or manager):
+        try:
+            platforms = settings.get_manager_platforms()
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+        if manager:
+            for p in platforms.list_spatial_platforms():
+                try:
+                    dsn = resolve_spatial_dsn(p)
+                except ValueError:
+                    continue  # skip platforms with unresolvable dsn
+                candidates.append(dsn)
+
+        if platform is not None:
+            for name in platform:
+                platform_obj = platforms.get_spatial_platform(name)
+                dsn = resolve_spatial_dsn(platform_obj)
+                candidates.append(dsn)
+
+    if not candidates and settings.postgres_dsn is not None:
+        candidates.append(resolve_dsn_env_tokens(settings.postgres_dsn))
+
+    return candidates
+
+
+@app.callback()
+def alembic(
+    ctx: typer.Context,
+    platform: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--platform",
+            "-p",
+            help="Use (a) platform name(s) as an alembic command target.",
+        ),
+    ] = None,
+    manager: Annotated[
+        bool,
+        typer.Option(
+            help="Use platforms from the manager api as alembic targets.",
+        ),
+    ] = False,
+) -> None:
+    """Run alembic commands on platform databases.
+    Use '--platform/-p' or '--manager' to select the
+    target databases. Falls back to
+    `SPATIAL_POSTGRES_DSN` if no platform is specified."""
+    settings = Settings()
+    settings.configure_logging()
+
+    dsns = collect_platforms(settings, platform=platform, manager=manager)
+
+    if len(dsns) == 0:
+        raise typer.BadParameter(
+            "No platforms found. Use '--platform/-p', '--manager', or set "
+            "`SPATIAL_POSTGRES_DSN`."
+        )
+
+    controllers = [get_alembic_controller(dsn) for dsn in dsns]
+    ctx.ensure_object(dict)
+    ctx.obj["controllers"] = controllers

spatial/cli/imports.py

@@ -0,0 +1,89 @@
+"""Resolve ``<module>:<name>`` references passed on the command line.
+
+Workflows live in their own repositories, so the objects they hand to the
+CLI (Pydantic models, extractor callables) cannot be imported by the CLI
+itself. They are passed as ``<module>:<name>`` strings, resolved against
+the working directory, and validated against an expected kind.
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib import import_module
+from typing import Any, Callable, cast
+
+import pydantic as pyd
+import typer
+
+ModelClassParser = Callable[[str], type[pyd.BaseModel]]
+CallableParser = Callable[[str], Callable[..., Any]]
+
+
+def import_member(reference: str) -> tuple[Any, str, str]:
+    """Import the member named by ``<module>:<name>``.
+
+    The working directory is added to ``sys.path`` so a workflow repository
+    can point at its own modules without being installed.
+
+    Returns
+    -------
+    tuple[Any, str, str]
+        The imported object, its name, and its module path.
+
+    Raises
+    ------
+    typer.BadParameter
+        If *reference* is malformed or the module cannot be imported.
+    """
+    if ":" not in reference:
+        raise typer.BadParameter(
+            f"'{reference}' is not a '<module>:<name>' reference."
+        )
+    module_name, name = reference.rsplit(":", 1)
+    if not module_name or not name:
+        raise typer.BadParameter(
+            f"'{reference}' is not a '<module>:<name>' reference."
+        )
+
+    cwd = "."
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+
+    try:
+        module = import_module(module_name)
+    except ImportError as exc:
+        raise typer.BadParameter(
+            f"Cannot import module '{module_name}' for reference '{reference}': {exc}"
+        ) from exc
+
+    member = getattr(module, name, None)
+    if member is None:
+        raise typer.BadParameter(
+            f"'{name}' does not exist in module '{module_name}'."
+        )
+    return member, name, module_name
+
+
+def parse_model_class(reference: str) -> type[pyd.BaseModel]:
+    """Parse ``<module>:<name>`` into a Pydantic model class."""
+    member, name, module_name = import_member(reference)
+    if not isinstance(member, type) or not issubclass(member, pyd.BaseModel):
+        raise typer.BadParameter(
+            f"'{name}' in module '{module_name}' is not a Pydantic model."
+        )
+    return member
+
+
+def parse_callable(reference: str) -> Callable[..., Any]:
+    """Parse ``<module>:<name>`` into a callable."""
+    member, name, module_name = import_member(reference)
+    if not callable(member):
+        raise typer.BadParameter(
+            f"'{name}' in module '{module_name}' is not callable."
+        )
+    return cast(Callable[..., Any], member)
+
+
+def parse_csv_paths(value: str) -> list[str]:
+    """Parse a comma-separated list of paths, dropping empty entries."""
+    return [item.strip() for item in value.split(",") if item.strip()]

spatial/cli/manager.py

@@ -0,0 +1,161 @@
+"""Manager authentication and platform inspection commands.
+
+Staff log in with their user account (``spatial login``); the credentials
+are cached locally and used by the other commands instead of the shared
+service secret. The connection details (the platform's spatial DSN) are
+fetched from the manager; secret material inside it stays in the local
+environment via ``{env:...}`` placeholders.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from toolkit.client.auth import ManagerAuth
+from toolkit.exceptions import InvalidCredentials
+
+from spatial.conf import Settings
+from spatial.conf.credentials import Credential, CredentialStore
+
+console = Console()
+
+app = typer.Typer(help="Manager authentication and platform inspection.")
+platforms_app = typer.Typer(
+    help="List platforms on the manager.", invoke_without_command=True
+)
+
+_USERINFO = re.compile(r"//(?P<user>[^:/@]+)(?::[^@]*)?@")
+
+
+def _settings() -> Settings:
+    settings = Settings()
+    settings.configure_logging()
+    return settings
+
+
+def _mask_dsn(dsn: str) -> str:
+    """Hide the password in a DSN, keeping the scheme, user and host."""
+    return _USERINFO.sub(r"//\g<user>:***@", dsn)
+
+
+def _require_manager_url(settings: Settings) -> str:
+    if settings.manager_url is None:
+        raise typer.BadParameter("`SPATIAL_MANAGER_URL` must be set.")
+    return str(settings.manager_url)
+
+
+@app.command("login")
+def login(
+    username: Annotated[
+        Optional[str],
+        typer.Option("--username", "-u", help="Your manager username."),
+    ] = None,
+) -> None:
+    """Log in to the manager api and cache the credentials locally."""
+    settings = _settings()
+    url = _require_manager_url(settings)
+    if username is None:
+        username = typer.prompt("Username")
+    password = typer.prompt("Password", hide_input=True)
+
+    try:
+        ManagerAuth(username, password, url)
+    except InvalidCredentials:
+        raise typer.BadParameter("The credentials are not valid.")
+
+    store = CredentialStore(settings.auth_file)
+    store.save(Credential(manager_url=url, username=username, password=password))
+    console.print(
+        f"Logged in as [bold]{username}[/bold] on {url}. "
+        f"Credentials saved to {settings.auth_file}."
+    )
+
+
+@app.command("logout")
+def logout() -> None:
+    """Delete the locally cached manager credentials."""
+    settings = _settings()
+    store = CredentialStore(settings.auth_file)
+    if store.load() is None:
+        console.print("No cached credentials.")
+        return
+    if typer.confirm("Delete the cached credentials?"):
+        store.clear()
+        console.print("Logged out.")
+
+
+@app.command("whoami")
+def whoami() -> None:
+    """Show the manager identity the CLI would use."""
+    settings = _settings()
+    credential = CredentialStore(settings.auth_file).load()
+    if credential is not None:
+        console.print(f"User: {credential.username}")
+        console.print(f"Manager: {credential.manager_url}")
+        console.print("Auth: cached user credentials")
+        return
+    if settings.secret_hs256 is not None:
+        console.print("User: <service account>")
+        console.print(f"Manager: {settings.manager_url}")
+        console.print("Auth: self-signed service secret")
+        return
+    console.print("Not logged in. Run `spatial login`, or set `SPATIAL_SECRET_HS256`.")
+
+
+def _list_platforms(settings: Settings) -> None:
+    rows = settings.get_manager_platforms().ixmp4.cached_list()
+    table = Table(title=f"Platforms on {settings.manager_url}")
+    table.add_column("slug")
+    table.add_column("name")
+    table.add_column("accessibility")
+    table.add_column("spatial")
+    table.add_column("dsn")
+    for platform in rows:
+        has_spatial = bool(getattr(platform, "spatial_dsn", None))
+        dsn_access = (
+            "visible" if getattr(platform, "is_mutable", False) else "hidden"
+        )
+        table.add_row(
+            platform.slug,
+            platform.name,
+            str(platform.accessibility),
+            "yes" if has_spatial else "no",
+            dsn_access if has_spatial else "-",
+        )
+    console.print(table)
+
+
+@platforms_app.callback()
+def platforms(
+    ctx: typer.Context,
+) -> None:
+    """List the platforms you can access on the manager."""
+    if ctx.invoked_subcommand is not None:
+        return
+    _list_platforms(_settings())
+
+
+@platforms_app.command("show")
+def platforms_show(
+    slug: Annotated[str, typer.Argument(help="Platform slug.")],
+) -> None:
+    """Show the connection details of one platform."""
+    settings = _settings()
+    platform = settings.get_manager_platforms().get_spatial_platform(slug)
+
+    console.print(f"[bold]{platform.name}[/bold] ({platform.slug})")
+    console.print(f"accessibility: {platform.accessibility}")
+    if getattr(platform, "is_mutable", False):
+        console.print(f"spatial DSN: {_mask_dsn(str(platform.spatial_dsn))}")
+    else:
+        console.print(
+            "spatial DSN: hidden (you are not a manager of this platform)"
+        )
+        console.print(f"spatial URL: {platform.spatial_dsn}")
+
+
+__all__ = ["app", "platforms_app"]

spatial/cli/server.py

@@ -0,0 +1,24 @@
+import typer
+import uvicorn
+
+
+app = typer.Typer(help="CLI for starting the spatial server.")
+
+
+@app.command()
+def start(
+    host: str = typer.Option(
+        "127.0.0.1",
+        help="The hostname to bind to.",
+    ),
+    port: int = typer.Option(
+        9000,
+        help="Requested server port.",
+    ),
+) -> None:
+    """Start the spatial server."""
+    uvicorn.run(
+        "spatial.server.app:app",
+        host=host,
+        port=port,
+    )