xoople-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/PKG-INFO

@@ -1,18 +1,16 @@
 Metadata-Version: 2.4
 Name: xoople-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Command-line interface for the Xoople Products API.
 License-Expression: LicenseRef-Xoople-Proprietary
 License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: xoople-sdk>=0.3.0
+Requires-Dist: xoople-sdk>=0.6.0
 Requires-Dist: cyclopts>=4.18,<5
 Requires-Dist: rich>=13.7
-Requires-Dist: xoople-sdk[entra]>=0.3.0 ; extra == 'entra'
 Requires-Python: >=3.12
 Project-URL: Homepage, https://xoople.com
-Provides-Extra: entra
 Description-Content-Type: text/markdown
 
 # xoople-cli
@@ -41,6 +39,49 @@ output pipes into `jq`.
 | `usage` | `history` `limits` |
 | `catalog` | `products` `measures` `designs` |
 | `access` | `me` `token` `features` |
+| `auth` | `login` `logout` `status` |
+
+## Signing in
+
+`auth login` signs in through the browser with PKCE and stores the session at
+`$XDG_CONFIG_HOME/xoople/session.json` (`~/.config/xoople/session.json` by
+default), readable only by you. Every later command uses that session when
+no `--token` is given, and refreshes it when the
+access token is close to expiry.
+
+```console
+$ export XOOPLE_API_URL=https://api.xoople.com
+$ xoople auth login
+$ xoople analyses list
+```
+
+`auth login` reads the CIAM client ID from the API. `--ciam-client-id`
+(`XOOPLE_CIAM_CLIENT_ID`) overrides it. `auth status` exits `3` when there is no
+stored session, so a script can test for a sign-in. `--ciam-redirect-uri` (`XOOPLE_CIAM_REDIRECT_URI`) overrides the
+loopback URI the browser returns to; it must match a URI registered for the
+CIAM client.
+
+## API keys
+
+An API key lets a script or a CI job run the CLI without a browser sign-in.
+Create one on the **API keys** section of your Xoople profile page (`/profile`).
+The key starts with `sk_` and is shown once, so store it in a secret manager.
+
+A key belongs to one organization membership. It acts as you, in the
+organization that was active when you created it, with that membership's roles.
+To work in a different organization, create a key there.
+
+Pass the key as the token. It takes precedence over a stored session:
+
+```console
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=sk_...
+$ xoople access me
+```
+
+The API accepts at most 300 API key requests a minute from one IP address. The
+CLI retries rate-limited GETs and replay-safe writes with backoff, then exits
+`8`. Any other write exits `8` on the first 429, with no retry. Revoke a key on
+the same profile page when you no longer need it.
 
 ## Submitting an analysis
 
@@ -59,7 +100,9 @@ non-zero if it does not reach `COMPLETE`.
 
 ## Exit codes
 
-`0` success · `1` unexpected CLI error · `2` usage error · `3` unauthenticated · `4` forbidden ·
+`0` success · `1` unexpected CLI error · `2` usage error ·
+`3` unauthenticated, including a failed or absent sign-in · `4` forbidden ·
 `5` not found · `6` bad request or validation · `7` conflict · `8` rate limited ·
 `9` server error · `10` connection failure · `11` unreadable response ·
-`12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out.
+`12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out ·
+`14` the analysis was deleted.

xoople_cli-0.4.0/README.md

@@ -0,0 +1,93 @@
+# xoople-cli
+
+Command-line interface for the Xoople Products API, over [`xoople-sdk`](../xoople-sdk).
+
+```console
+$ uv tool install xoople-cli
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=...
+$ xoople analyses list
+```
+
+Every command reads `--api-url` and `--token` from `XOOPLE_API_URL` and
+`XOOPLE_TOKEN`. `--json` prints the API response verbatim instead of a table, so
+output pipes into `jq`.
+
+## Commands
+
+| Group | Commands |
+| --- | --- |
+| `analyses` | `list` `get` `create` `update` `cancel` `estimate` |
+| `runs` | `list` `get` |
+| `outputs` | `list` `get` `access-url` |
+| `schedules` | `list` `get` `create` `pause` `resume` `cancel` `run` `estimate-run` |
+| `events` | `list` `get` |
+| `usage` | `history` `limits` |
+| `catalog` | `products` `measures` `designs` |
+| `access` | `me` `token` `features` |
+| `auth` | `login` `logout` `status` |
+
+## Signing in
+
+`auth login` signs in through the browser with PKCE and stores the session at
+`$XDG_CONFIG_HOME/xoople/session.json` (`~/.config/xoople/session.json` by
+default), readable only by you. Every later command uses that session when
+no `--token` is given, and refreshes it when the
+access token is close to expiry.
+
+```console
+$ export XOOPLE_API_URL=https://api.xoople.com
+$ xoople auth login
+$ xoople analyses list
+```
+
+`auth login` reads the CIAM client ID from the API. `--ciam-client-id`
+(`XOOPLE_CIAM_CLIENT_ID`) overrides it. `auth status` exits `3` when there is no
+stored session, so a script can test for a sign-in. `--ciam-redirect-uri` (`XOOPLE_CIAM_REDIRECT_URI`) overrides the
+loopback URI the browser returns to; it must match a URI registered for the
+CIAM client.
+
+## API keys
+
+An API key lets a script or a CI job run the CLI without a browser sign-in.
+Create one on the **API keys** section of your Xoople profile page (`/profile`).
+The key starts with `sk_` and is shown once, so store it in a secret manager.
+
+A key belongs to one organization membership. It acts as you, in the
+organization that was active when you created it, with that membership's roles.
+To work in a different organization, create a key there.
+
+Pass the key as the token. It takes precedence over a stored session:
+
+```console
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=sk_...
+$ xoople access me
+```
+
+The API accepts at most 300 API key requests a minute from one IP address. The
+CLI retries rate-limited GETs and replay-safe writes with backoff, then exits
+`8`. Any other write exits `8` on the first 429, with no retry. Revoke a key on
+the same profile page when you no longer need it.
+
+## Submitting an analysis
+
+The product spec is deeply nested and differs per product, so `create` and
+`estimate` take it as JSON rather than as flags:
+
+```console
+$ xoople catalog designs --json | jq '.[0].spec_fragment' > spec.json
+$ # fill in period and aoi, then:
+$ xoople analyses create -f spec.json --display-name "South Wales NDVI" --wait
+```
+
+The file holds either the bare spec or a whole create request (anything with a
+`spec` key). `-f -` reads stdin. `--wait` polls the initial run and exits
+non-zero if it does not reach `COMPLETE`.
+
+## Exit codes
+
+`0` success · `1` unexpected CLI error · `2` usage error ·
+`3` unauthenticated, including a failed or absent sign-in · `4` forbidden ·
+`5` not found · `6` bad request or validation · `7` conflict · `8` rate limited ·
+`9` server error · `10` connection failure · `11` unreadable response ·
+`12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out ·
+`14` the analysis was deleted.

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xoople-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Command-line interface for the Xoople Products API."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -11,14 +11,11 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "xoople-sdk>=0.3.0",
+    "xoople-sdk>=0.6.0",
     "cyclopts>=4.18,<5",
     "rich>=13.7",
 ]
 
-[project.optional-dependencies]
-entra = ["xoople-sdk[entra]>=0.3.0"]
-
 [project.scripts]
 xoople = "xoople.cli.main:main"
 

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xoople-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Command-line interface for the Xoople Products API."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -13,7 +13,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-  "xoople-sdk>=0.3.0",
+  "xoople-sdk>=0.6.0",
   # Cyclopts parses docstrings for parameter help so signatures stay plain,
   # supports union types and Pydantic models natively, and owns its parser.
   # Global options + dependency injection go through the meta-app launcher
@@ -22,13 +22,6 @@ dependencies = [
   "rich>=13.7",
 ]
 
-[project.optional-dependencies]
-# Mirrors xoople-sdk[entra]: internal callers authenticating with Entra ID via
-# `--entra-scope`. Not needed for the token path.
-entra = [
-  "xoople-sdk[entra]>=0.3.0",
-]
-
 [project.scripts]
 xoople = "xoople.cli.main:main"
 

xoople_cli-0.4.0/src/xoople/cli/_ciam.py

@@ -0,0 +1,71 @@
+"""Which CIAM client the CLI signs in as, and how a failed sign-in is reported.
+
+The SDK owns the sign-in, browser leg included, and the session file, because
+a `xoople-cli` connection profile reads that file too.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, Self
+
+from xoople.cli._errors import LoginFailed
+from xoople.sdk.auth import CiamUserSession, ciam_sign_in
+from xoople.sdk.errors import CredentialError
+
+DEFAULT_REDIRECT_URI = "http://localhost:8976/callback"
+"""Fixed, because CIAM matches a redirect URI exactly and must hold this one."""
+
+
+class _SignIn(Protocol):
+    def __call__(
+        self, *, client_id: str, redirect_uri: str, announce: Callable[[str], None]
+    ) -> CiamUserSession: ...
+
+
+# Tests supply a lookup that makes no HTTP call.
+type ClientIdLookup = Callable[[str], str]
+
+
+@dataclass(frozen=True, slots=True)
+class CiamConfig:
+    """What a login needs: the CIAM client and the URI the browser comes back to."""
+
+    client_id: str
+    redirect_uri: str = DEFAULT_REDIRECT_URI
+
+    @classmethod
+    def resolve(
+        cls,
+        client_id: str | None,
+        redirect_uri: str | None,
+        *,
+        base_url: str | None,
+        discover: ClientIdLookup,
+    ) -> Self:
+        """An explicit client wins. Otherwise the API names its own client."""
+        if not client_id:
+            if not base_url:
+                raise LoginFailed(
+                    "no CIAM client: pass --api-url, --ciam-client-id or set XOOPLE_CIAM_CLIENT_ID"
+                )
+            try:
+                client_id = discover(base_url)
+            except CredentialError as exc:
+                raise LoginFailed(f"{exc}: check --api-url or pass --ciam-client-id") from None
+        return cls(client_id=client_id, redirect_uri=redirect_uri or DEFAULT_REDIRECT_URI)
+
+
+def login(
+    config: CiamConfig,
+    *,
+    announce: Callable[[str], None],
+    sign_in: _SignIn = ciam_sign_in,
+) -> CiamUserSession:
+    """Run one browser sign-in and return the session it produced."""
+    try:
+        return sign_in(
+            client_id=config.client_id, redirect_uri=config.redirect_uri, announce=announce
+        )
+    except CredentialError as exc:
+        # One exit code covers every sign-in failure. The SDK message says which.
+        raise LoginFailed(str(exc)) from None

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/src/xoople/cli/_context.py

@@ -1,11 +1,18 @@
 from collections.abc import Callable
 from dataclasses import dataclass, field
-from typing import Annotated
+from typing import Annotated, Protocol
 
 from cyclopts import Parameter
+from xoople.cli import _ciam
 from xoople.cli._errors import UsageError
 from xoople.sdk import Config, CredentialProvider, XoopleClient
-from xoople.sdk.auth import EntraCredential, StaticToken
+from xoople.sdk import session as session_file
+from xoople.sdk.auth import (
+    CiamUserCredentials,
+    CiamUserSession,
+    StaticToken,
+    ciam_discover_client_id,
+)
 
 
 @dataclass(frozen=True)
@@ -14,7 +21,8 @@ class Credentials:
 
     base_url: str | None = None
     token: str | None = None
-    entra_scope: str | None = None
+    ciam_client_id: str | None = None
+    ciam_redirect_uri: str | None = None
     timeout: float = 30.0
     max_retries: int = 3
 
@@ -22,6 +30,15 @@ class Credentials:
 # The client factory is swapped for a fake in tests.
 type ClientFactory = Callable[[Credentials], XoopleClient]
 
+
+class LoginRunner(Protocol):
+    """Runs one browser sign-in. Tests supply one that opens no browser."""
+
+    def __call__(
+        self, config: _ciam.CiamConfig, *, announce: Callable[[str], None]
+    ) -> CiamUserSession: ...
+
+
 # The launcher injects ``Settings`` via ``parse=False``; commands stay plain
 # functions and tests drive them over a fake transport.
 type SettingsParam = Annotated[Settings, Parameter(parse=False)]
@@ -45,6 +62,8 @@ class Settings:
 
     credentials: Credentials
     factory: ClientFactory
+    login: LoginRunner = _ciam.login
+    discover: _ciam.ClientIdLookup = ciam_discover_client_id
     as_json: bool = False
     _client: XoopleClient | None = field(default=None, repr=False)
 
@@ -59,12 +78,19 @@ class Settings:
             self._client = None
 
 
+def _persist_session(session: CiamUserSession) -> None:
+    session_file.write_session(session)
+
+
 def _credential_provider(credentials: Credentials) -> CredentialProvider:
-    if credentials.entra_scope:
-        return EntraCredential(credentials.entra_scope)
-    if not credentials.token:
-        raise UsageError("no credentials: pass --token, set XOOPLE_TOKEN, or pass --entra-scope")
-    return StaticToken(credentials.token)
+    if credentials.token:
+        return StaticToken(credentials.token)
+    session = session_file.read_session()
+    if session is not None:
+        # The credential refreshes a user token itself. Store what it mints, so
+        # the next run does not spend another refresh token.
+        return CiamUserCredentials(session, on_refresh=_persist_session)
+    raise UsageError("no credentials: run `xoople auth login`, pass --token, or set XOOPLE_TOKEN")
 
 
 def build_client(credentials: Credentials) -> XoopleClient:

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/src/xoople/cli/_errors.py

@@ -4,6 +4,8 @@ from xoople.sdk import errors
 EXIT_CODES: dict[type[errors.XoopleError], int] = {
     errors.AuthenticationError: 3,
     errors.PermissionDeniedError: 4,
+    # Before its parent: `exit_code` takes the first class the error is an instance of.
+    errors.AnalysisDeletedError: 14,
     errors.NotFoundError: 5,
     errors.BadRequestError: 6,
     errors.ValidationError: 6,
@@ -32,6 +34,16 @@ class UsageError(CliError):
     exit_code = USAGE_EXIT
 
 
+class LoginFailed(CliError):
+    """A CIAM sign-in did not produce a session.
+
+    Takes the API's unauthenticated code: the outcome a caller must handle is
+    the same, so a script does not need a second number for it.
+    """
+
+    exit_code = EXIT_CODES[errors.AuthenticationError]
+
+
 class RunFailed(CliError):
     """``--wait`` finished, but the run ended in a non-``COMPLETE`` state."""
 

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/src/xoople/cli/_output.py

@@ -7,12 +7,9 @@ from rich.table import Table
 
 type Column = tuple[str, str]
 
-# Fields holding a 0..1 fraction. A column headed PROGRESS showing `0.42` reads
-# as a bug, and `estimate_confidence` is the same unit, so both render as whole
-# percent. Keyed on the field name rather than declared per column: the unit
-# belongs to the field, so it must not depend on which emit function a command
-# happened to call. The generated models carry no `ge`/`le` metadata to infer it
-# from — if the spec ever declares bounds, read them instead of this set.
+# Fields holding a 0..1 fraction, rendered as whole percent. Keyed on the field name
+# because the unit belongs to the field, not the emitting command. The generated models
+# carry no `ge`/`le` bounds to infer it from; if the spec adds them, read those instead.
 _FRACTION_FIELDS = frozenset({"fraction", "estimate_confidence"})
 
 # Piped output must not depend on the terminal that happened to launch it, so a

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/src/xoople/cli/_spec.py

@@ -25,7 +25,7 @@ def _explain(exc: ValidationError) -> str:
 
 
 def load_create_request(
-    path: Path, display_name: str | None = None
+    path: Path, display_name: str | None = None, project: str | None = None
 ) -> models.CreateAnalysisRequest:
     """Read a create/estimate body from a JSON file (``-`` for stdin).
 
@@ -40,6 +40,6 @@ def load_create_request(
     # say so in its return type.
     body: dict[str, object] = {str(key): value for key, value in document.items()}
     try:
-        return create_request_from(body, display_name)
+        return create_request_from(body, display_name, project)
     except ValidationError as exc:
         raise UsageError(_explain(exc)) from exc

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/src/xoople/cli/analyses.py

@@ -105,6 +105,7 @@ def create(
     settings: SettingsParam,
     spec_file: Annotated[Path, _SPEC_FILE],
     display_name: str | None = None,
+    project: str | None = None,
     idempotency_key: str | None = None,
     wait: bool = False,
     poll_interval: float = 5.0,
@@ -118,6 +119,10 @@ def create(
         JSON spec, or a whole create request. Use - for stdin.
     display_name:
         Label for the analysis; overrides the spec file's.
+    project:
+        Project that holds the analysis, as a uid or projects/{uid}; overrides the spec
+        file's. Omit it to use the organisation's default project. An M2M token always
+        gets 403 for a named project other than the default project.
     idempotency_key:
         Reuse a previous key to replay a submission instead of duplicating it.
     wait:
@@ -127,7 +132,7 @@ def create(
     wait_timeout:
         Give up waiting after this many seconds.
     """
-    body = load_create_request(spec_file, display_name)
+    body = load_create_request(spec_file, display_name, project)
     analysis = settings.client().analyses.create(body, idempotency_key=idempotency_key)
     if not wait:
         emit_one(analysis, FIELDS, as_json=settings.as_json)

xoople_cli-0.4.0/src/xoople/cli/auth.py

@@ -0,0 +1,70 @@
+from cyclopts import App
+from pydantic import BaseModel
+from xoople.cli import _ciam
+from xoople.cli._context import SettingsParam
+from xoople.cli._errors import LoginFailed
+from xoople.cli._output import emit_one, note
+from xoople.sdk import session as session_file
+from xoople.sdk.auth import normalize_api_url
+
+app = App(
+    name="auth",
+    help="Sign in to Xoople, and show or discard the stored session.",
+)
+
+FIELDS = [("EMAIL", "email"), ("ORGANIZATION", "org_id"), ("EXPIRES", "expires_at")]
+
+
+class _StatusRow(BaseModel):
+    """The part of a session that is safe to print. It carries no token."""
+
+    email: str | None
+    org_id: str | None
+    expires_at: int
+
+
+def _bound_api_url(base_url: str | None) -> str | None:
+    """The API a profile may send this session's token to. None binds it to no profile."""
+    if not base_url:
+        return None
+    try:
+        return normalize_api_url(base_url)
+    except ValueError:
+        raise LoginFailed(f"{base_url!r} is not a URL: check --api-url") from None
+
+
+@app.command(name="login")
+def login(*, settings: SettingsParam) -> None:
+    """Sign in through the browser and store the session for later commands."""
+    config = _ciam.CiamConfig.resolve(
+        settings.credentials.ciam_client_id,
+        settings.credentials.ciam_redirect_uri,
+        base_url=settings.credentials.base_url,
+        discover=settings.discover,
+    )
+    api_url = _bound_api_url(settings.credentials.base_url)
+    note(f"Serving the sign-in callback on {config.redirect_uri}")
+    session = settings.login(config, announce=lambda url: note(f"Opening {url}"))
+    session = session.model_copy(update={"api_url": api_url})
+    path = session_file.write_session(session)
+    note(f"Signed in as {session.email or session.client_id}; session stored at {path}")
+
+
+@app.command(name="logout")
+def logout(*, settings: SettingsParam) -> None:
+    """Discard the stored session."""
+    del settings
+    if session_file.clear_session():
+        note("Signed out.")
+        return
+    note("No stored session.")
+
+
+@app.command(name="status")
+def status(*, settings: SettingsParam) -> None:
+    """Show who the stored session belongs to, and when it expires."""
+    session = session_file.read_session()
+    if session is None:
+        raise LoginFailed("no stored session: run `xoople auth login`")
+    row = _StatusRow(email=session.email, org_id=session.org_id, expires_at=session.expires_at)
+    emit_one(row, FIELDS, as_json=settings.as_json)

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/src/xoople/cli/catalog.py

@@ -32,7 +32,7 @@ def measures(
     product: str | None = None,
     domain: list[str] | None = None,
 ) -> None:
-    """List the bands, indices and contrasts you can request.
+    """List the bands, indices and indicators you can request.
 
     Parameters
     ----------
@@ -58,7 +58,6 @@ def measures(
     )
     for label, items in (
         ("indices", result.indices),
-        ("contrasts", result.contrasts),
         ("indicators", result.indicators),
     ):
         heading(label)
@@ -101,6 +100,25 @@ def projections(*, settings: SettingsParam, bbox: str) -> None:
     )
 
 
+@app.command(name="cloud-mask-presets")
+def cloud_mask_presets(*, settings: SettingsParam) -> None:
+    """List the scene-class masking presets, and the scene classes each one discards.
+
+    A preset name is what `cloud_mask_mode` accepts on an imagery request. The
+    classes are published here so a request never has to restate them.
+    """
+    result = settings.client().catalog.cloud_mask_presets()
+    emit(
+        result.presets,
+        [
+            ("MODE", "mode"),
+            ("EXCLUDED CLASSES", "excluded_classes"),
+            ("EXCLUDED CLASS NAMES", "excluded_class_names"),
+        ],
+        as_json=settings.as_json,
+    )
+
+
 @app.command(name="designs")
 def designs(*, settings: SettingsParam, product: str | None = None) -> None:
     """List the starting-point analysis designs. Their `spec_fragment` seeds a spec file.

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/src/xoople/cli/main.py

@@ -4,26 +4,43 @@ from cyclopts import App, CycloptsError, Parameter
 from xoople.cli import (
     access,
     analyses,
+    auth,
     catalog,
     events,
     outputs,
+    packages,
     projects,
     runs,
     schedules,
     usage,
 )
-from xoople.cli._context import ClientFactory, Credentials, Settings, build_client
+from xoople.cli._ciam import ClientIdLookup
+from xoople.cli._ciam import login as ciam_login
+from xoople.cli._context import (
+    ClientFactory,
+    Credentials,
+    LoginRunner,
+    Settings,
+    build_client,
+)
 from xoople.cli._errors import USAGE_EXIT, CliError, report
 from xoople.cli._output import note
 from xoople.cli._version import version
 from xoople.sdk import errors
+from xoople.sdk.auth import ciam_discover_client_id
 
 
-def create_app(factory: ClientFactory = build_client) -> App:
-    """The command tree, bound to a way of building clients.
+def create_app(
+    factory: ClientFactory = build_client,
+    login: LoginRunner = ciam_login,
+    discover: ClientIdLookup = ciam_discover_client_id,
+) -> App:
+    """The command tree, bound to a way of building clients and signing in.
 
     Tests build the tree over a fake transport rather than reaching into module
     globals, so every command runs its real argument parsing and rendering.
+    `login` is the same seam for the sign-in, which opens a browser, and
+    `discover` for the client ID lookup, which calls the API.
     """
     app = App(
         name="xoople",
@@ -34,18 +51,23 @@ def create_app(factory: ClientFactory = build_client) -> App:
     app.command(projects.app)
     app.command(runs.app)
     app.command(outputs.app)
+    app.command(packages.app)
     app.command(schedules.app)
     app.command(events.app)
     app.command(usage.app)
     app.command(catalog.app)
     app.command(access.app)
+    app.command(auth.app)
 
     @app.meta.default
     def launcher(
         *tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)],
         api_url: Annotated[str | None, Parameter(env_var="XOOPLE_API_URL")] = None,
         token: Annotated[str | None, Parameter(env_var="XOOPLE_TOKEN")] = None,
-        entra_scope: Annotated[str | None, Parameter(env_var="XOOPLE_ENTRA_SCOPE")] = None,
+        ciam_client_id: Annotated[str | None, Parameter(env_var="XOOPLE_CIAM_CLIENT_ID")] = None,
+        ciam_redirect_uri: Annotated[
+            str | None, Parameter(env_var="XOOPLE_CIAM_REDIRECT_URI")
+        ] = None,
         timeout: Annotated[float, Parameter()] = 30.0,
         max_retries: Annotated[int, Parameter()] = 3,
         json_output: Annotated[bool, Parameter(name="--json")] = False,
@@ -58,9 +80,12 @@ def create_app(factory: ClientFactory = build_client) -> App:
             Base URL of the Xoople API.
         token:
             Bearer token.
-        entra_scope:
-            Authenticate with Entra ID for this scope instead of a token
-            (internal use; needs the entra extra).
+        ciam_client_id:
+            Xoople CIAM client ID, used by `auth login`. Without it, the CLI
+            reads the client ID from the API.
+        ciam_redirect_uri:
+            Loopback URI the browser returns the sign-in to. It must match the
+            URI registered for the CIAM client.
         timeout:
             Per-request timeout, in seconds.
         max_retries:
@@ -77,11 +102,14 @@ def create_app(factory: ClientFactory = build_client) -> App:
             credentials=Credentials(
                 base_url=api_url,
                 token=token,
-                entra_scope=entra_scope,
+                ciam_client_id=ciam_client_id,
+                ciam_redirect_uri=ciam_redirect_uri,
                 timeout=timeout,
                 max_retries=max_retries,
             ),
             factory=factory,
+            login=login,
+            discover=discover,
             as_json=json_output,
         )
         try:

{xoople_cli-0.2.0 → xoople_cli-0.4.0}/src/xoople/cli/outputs.py

@@ -75,3 +75,37 @@ def access_url(
         analysis, output, ttl_seconds=ttl_seconds
     )
     emit_model(result, as_json=settings.as_json)
+
+
+@app.command(name="summary")
+def summary(analysis: str, output: str, *, settings: SettingsParam) -> None:
+    """Show an output's summary: aggregate coverage, grain and pixel statistics.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis the output belongs to.
+    output:
+        The output whose summary to show.
+    """
+    emit_model(
+        settings.client().analyses.outputs.get_summary(analysis, output),
+        as_json=settings.as_json,
+    )
+
+
+@app.command(name="refresh-summary")
+def refresh_summary(analysis: str, output: str, *, settings: SettingsParam) -> None:
+    """Start (or join) an asynchronous recomputation of an output's summary.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis the output belongs to.
+    output:
+        The output whose summary to refresh.
+    """
+    emit_model(
+        settings.client().analyses.outputs.refresh_summary(analysis, output),
+        as_json=settings.as_json,
+    )

xoople_cli-0.4.0/src/xoople/cli/packages.py

@@ -0,0 +1,92 @@
+from typing import Annotated
+
+from cyclopts import App, Parameter
+from xoople.cli._context import SettingsParam, at_least_one
+from xoople.cli._output import emit, emit_model
+
+app = App(
+    name="packages",
+    help="Export an analysis as an immutable Parquet package and mint access links.",
+)
+
+COLUMNS = [
+    ("PACKAGE", "package_id"),
+    ("STATE", "state"),
+    ("VERSION", "delta_version"),
+    ("ROWS", "row_count"),
+    ("CREATED", "create_time"),
+]
+
+
+@app.command(name="create")
+def create(analysis: str, *, settings: SettingsParam) -> None:
+    """Package an analysis's current output, or return the package that already holds it.
+
+    Parameters
+    ----------
+    analysis:
+        The ready analysis to package. Needs its owner and the parquet_packages feature.
+    """
+    emit_model(settings.client().analyses.packages.create(analysis), as_json=settings.as_json)
+
+
+@app.command(name="list")
+def list_packages(
+    analysis: str,
+    *,
+    settings: SettingsParam,
+    limit: Annotated[int | None, Parameter(validator=at_least_one)] = None,
+) -> None:
+    """List an analysis's packages, newest first.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis whose packages to list.
+    limit:
+        Stop after this many, instead of every page.
+    """
+    items = settings.client().analyses.packages.list(analysis, limit=limit)
+    emit(items, COLUMNS, as_json=settings.as_json)
+
+
+@app.command(name="get")
+def get(analysis: str, package: str, *, settings: SettingsParam) -> None:
+    """Show one package and whether it has settled.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis the package belongs to.
+    package:
+        The package to show.
+    """
+    emit_model(settings.client().analyses.packages.get(analysis, package), as_json=settings.as_json)
+
+
+@app.command(name="access-url")
+def access_url(
+    analysis: str,
+    package: str,
+    *,
+    settings: SettingsParam,
+    access_ttl_hours: int | None = None,
+) -> None:
+    """Mint links to a ready package: one zip of it, and its directory.
+
+    `archive_url` downloads the whole package as one zip file. `url` opens the
+    directory; copy it with `azcopy copy "<url>" ./package --recursive`.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis the package belongs to.
+    package:
+        The ready package to mint a link for.
+    access_ttl_hours:
+        How many hours the link stays valid, 1 to 168; the API picks 24.
+    """
+    result = settings.client().analyses.packages.generate_access_url(
+        analysis, package, access_ttl_hours=access_ttl_hours
+    )
+    emit_model(result, as_json=settings.as_json)

xoople_cli-0.4.0/src/xoople/cli/projects.py

@@ -0,0 +1,234 @@
+from typing import Annotated
+
+from cyclopts import App, Parameter
+from xoople.cli._context import SettingsParam, at_least_one
+from xoople.cli._output import emit, emit_model, emit_one, note
+
+app = App(
+    name="projects",
+    help="Organise analyses into projects and manage who belongs to them.",
+)
+
+COLUMNS = [
+    ("UID", "uid"),
+    ("NAME", "display_name"),
+    ("DEFAULT", "is_default"),
+    ("ARCHIVED", "archive_time"),
+]
+
+FIELDS = [
+    ("Name", "name"),
+    ("UID", "uid"),
+    ("Display name", "display_name"),
+    ("Description", "description"),
+    ("Default", "is_default"),
+    ("Archive time", "archive_time"),
+    ("Create time", "create_time"),
+    ("Update time", "update_time"),
+]
+
+
+@app.command(name="list")
+def list_projects(
+    *,
+    settings: SettingsParam,
+    limit: Annotated[int | None, Parameter(validator=at_least_one)] = None,
+) -> None:
+    """List your organisation's projects.
+
+    Parameters
+    ----------
+    limit:
+        Stop after this many, instead of every page.
+    """
+    emit(settings.client().projects.list(limit=limit), COLUMNS, as_json=settings.as_json)
+
+
+@app.command(name="create")
+def create(name: str, *, description: str | None = None, settings: SettingsParam) -> None:
+    """Create a project.
+
+    Parameters
+    ----------
+    name:
+        The project's display name.
+    description:
+        The project's description, at most 500 characters.
+    """
+    emit_one(settings.client().projects.create(name, description), FIELDS, as_json=settings.as_json)
+
+
+@app.command(name="get")
+def get(project: str, *, settings: SettingsParam) -> None:
+    """Show one project, archived or not.
+
+    Parameters
+    ----------
+    project:
+        The project to show.
+    """
+    emit_one(settings.client().projects.get(project), FIELDS, as_json=settings.as_json)
+
+
+@app.command(name="update")
+def update(
+    project: str,
+    *,
+    display_name: str | None = None,
+    description: str | None = None,
+    settings: SettingsParam,
+) -> None:
+    """Change a project's display name, its description, or both.
+
+    Parameters
+    ----------
+    project:
+        The project to change.
+    display_name:
+        The new display name.
+    description:
+        The new description. Pass an empty string to clear it.
+    """
+    emit_one(
+        settings.client().projects.update(
+            project, display_name=display_name, description=description
+        ),
+        FIELDS,
+        as_json=settings.as_json,
+    )
+
+
+MEMBER_COLUMNS = [
+    ("SUBJECT", "subject_id"),
+    ("NAME", "display_name"),
+    ("EMAIL", "email"),
+    ("ROLE", "role"),
+]
+
+
+@app.command(name="members")
+def members(project: str, *, settings: SettingsParam) -> None:
+    """List a project's members and their project role.
+
+    The default project admits every organisation member, so it lists none.
+
+    Parameters
+    ----------
+    project:
+        The project to list.
+    """
+    listed = settings.client().projects.list_members(project)
+    if settings.as_json:
+        emit_model(listed, as_json=True)
+    elif listed.admits_whole_organization:
+        note(f"[dim]Every organisation member belongs to {project}[/dim]")
+    else:
+        emit(listed.members, MEMBER_COLUMNS, as_json=False)
+
+
+@app.command(name="add-member")
+def add_member(project: str, subject_id: str, *, settings: SettingsParam) -> None:
+    """Add a subject to a project.
+
+    Parameters
+    ----------
+    project:
+        The project to add to.
+    subject_id:
+        The subject to add.
+    """
+    emit_model(settings.client().projects.add_member(project, subject_id), as_json=settings.as_json)
+
+
+@app.command(name="remove-member")
+def remove_member(project: str, subject: str, *, settings: SettingsParam) -> None:
+    """Remove a subject from a project.
+
+    Parameters
+    ----------
+    project:
+        The project to remove from.
+    subject:
+        The subject to remove.
+    """
+    settings.client().projects.remove_member(project, subject)
+    note(f"[dim]{subject} is no longer a member of {project}[/dim]")
+
+
+@app.command(name="move")
+def move(project: str, destination: str, analyses: list[str], *, settings: SettingsParam) -> None:
+    """Move named analyses into another project, pausing their schedules.
+
+    Parameters
+    ----------
+    project:
+        The project the analyses are in now.
+    destination:
+        The project to move them into.
+    analyses:
+        The analysis identifiers to move, at most 500 per call.
+    """
+    emit_model(
+        settings.client().projects.move_analyses_to_project(project, analyses, destination),
+        as_json=settings.as_json,
+    )
+
+
+@app.command(name="archive")
+def archive(project: str, *, settings: SettingsParam) -> None:
+    """Archive a project and pause its schedules.
+
+    The default project cannot be archived.
+
+    Parameters
+    ----------
+    project:
+        The project to archive.
+    """
+    settings.client().projects.archive(project)
+    note(f"[dim]{project} is archived[/dim]")
+
+
+@app.command(name="delete")
+def delete(project: str, *, settings: SettingsParam) -> None:
+    """Delete an archived project and remove its stored data.
+
+    The project must hold no analyses. It counts against the project limit
+    until storage removal finishes.
+
+    Parameters
+    ----------
+    project:
+        The archived project to delete.
+    """
+    settings.client().projects.delete(project)
+    note(f"[dim]{project} is deleted; its storage is being removed[/dim]")
+
+
+@app.command(name="record-access")
+def record_access(project: str, *, settings: SettingsParam) -> None:
+    """Record that you opened a project, which orders `projects recent`.
+
+    Parameters
+    ----------
+    project:
+        The project you opened.
+    """
+    settings.client().projects.record_access(project)
+    note(f"[dim]{project} is your most recent project[/dim]")
+
+
+@app.command(name="recent")
+def recent(
+    *,
+    settings: SettingsParam,
+    limit: Annotated[int | None, Parameter(validator=at_least_one)] = None,
+) -> None:
+    """List the projects you opened most recently.
+
+    Parameters
+    ----------
+    limit:
+        Return this many, instead of the default four.
+    """
+    emit(settings.client().projects.recent(limit=limit), COLUMNS, as_json=settings.as_json)

xoople_cli-0.2.0/README.md

@@ -1,48 +0,0 @@
-# xoople-cli
-
-Command-line interface for the Xoople Products API, over [`xoople-sdk`](../xoople-sdk).
-
-```console
-$ uv tool install xoople-cli
-$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_TOKEN=...
-$ xoople analyses list
-```
-
-Every command reads `--api-url` and `--token` from `XOOPLE_API_URL` and
-`XOOPLE_TOKEN`. `--json` prints the API response verbatim instead of a table, so
-output pipes into `jq`.
-
-## Commands
-
-| Group | Commands |
-| --- | --- |
-| `analyses` | `list` `get` `create` `update` `cancel` `estimate` |
-| `runs` | `list` `get` |
-| `outputs` | `list` `get` `access-url` |
-| `schedules` | `list` `get` `create` `pause` `resume` `cancel` `run` `estimate-run` |
-| `events` | `list` `get` |
-| `usage` | `history` `limits` |
-| `catalog` | `products` `measures` `designs` |
-| `access` | `me` `token` `features` |
-
-## Submitting an analysis
-
-The product spec is deeply nested and differs per product, so `create` and
-`estimate` take it as JSON rather than as flags:
-
-```console
-$ xoople catalog designs --json | jq '.[0].spec_fragment' > spec.json
-$ # fill in period and aoi, then:
-$ xoople analyses create -f spec.json --display-name "South Wales NDVI" --wait
-```
-
-The file holds either the bare spec or a whole create request (anything with a
-`spec` key). `-f -` reads stdin. `--wait` polls the initial run and exits
-non-zero if it does not reach `COMPLETE`.
-
-## Exit codes
-
-`0` success · `1` unexpected CLI error · `2` usage error · `3` unauthenticated · `4` forbidden ·
-`5` not found · `6` bad request or validation · `7` conflict · `8` rate limited ·
-`9` server error · `10` connection failure · `11` unreadable response ·
-`12` run finished in a non-`COMPLETE` state · `13` `--wait` timed out.

xoople_cli-0.2.0/src/xoople/cli/projects.py

@@ -1,118 +0,0 @@
-from typing import Annotated
-
-from cyclopts import App, Parameter
-from xoople.cli._context import SettingsParam, at_least_one
-from xoople.cli._output import emit, emit_model, emit_one, note
-
-app = App(
-    name="projects",
-    help="Organise analyses into projects and manage who belongs to them.",
-)
-
-COLUMNS = [
-    ("UID", "uid"),
-    ("NAME", "display_name"),
-    ("DEFAULT", "is_default"),
-    ("ARCHIVED", "archive_time"),
-]
-
-FIELDS = [
-    ("Name", "name"),
-    ("UID", "uid"),
-    ("Display name", "display_name"),
-    ("Default", "is_default"),
-    ("Archive time", "archive_time"),
-    ("Create time", "create_time"),
-    ("Update time", "update_time"),
-]
-
-
-@app.command(name="list")
-def list_projects(
-    *,
-    settings: SettingsParam,
-    limit: Annotated[int | None, Parameter(validator=at_least_one)] = None,
-) -> None:
-    """List your organisation's projects.
-
-    Parameters
-    ----------
-    limit:
-        Stop after this many, instead of every page.
-    """
-    emit(settings.client().projects.list(limit=limit), COLUMNS, as_json=settings.as_json)
-
-
-@app.command(name="create")
-def create(name: str, *, settings: SettingsParam) -> None:
-    """Create a project.
-
-    Parameters
-    ----------
-    name:
-        The project's display name.
-    """
-    emit_one(settings.client().projects.create(name), FIELDS, as_json=settings.as_json)
-
-
-@app.command(name="add-member")
-def add_member(project: str, subject_id: str, *, settings: SettingsParam) -> None:
-    """Add a subject to a project.
-
-    Parameters
-    ----------
-    project:
-        The project to add to.
-    subject_id:
-        The subject to add.
-    """
-    emit_model(settings.client().projects.add_member(project, subject_id), as_json=settings.as_json)
-
-
-@app.command(name="remove-member")
-def remove_member(project: str, subject: str, *, settings: SettingsParam) -> None:
-    """Remove a subject from a project.
-
-    Parameters
-    ----------
-    project:
-        The project to remove from.
-    subject:
-        The subject to remove.
-    """
-    settings.client().projects.remove_member(project, subject)
-    note(f"[dim]{subject} is no longer a member of {project}[/dim]")
-
-
-@app.command(name="move")
-def move(project: str, destination: str, analyses: list[str], *, settings: SettingsParam) -> None:
-    """Move named analyses into another project, pausing their schedules.
-
-    Parameters
-    ----------
-    project:
-        The project the analyses are in now.
-    destination:
-        The project to move them into.
-    analyses:
-        The analysis identifiers to move, at most 500 per call.
-    """
-    emit_model(
-        settings.client().projects.move_analyses_to_project(project, analyses, destination),
-        as_json=settings.as_json,
-    )
-
-
-@app.command(name="archive")
-def archive(project: str, *, settings: SettingsParam) -> None:
-    """Archive a project and pause its schedules.
-
-    The default project cannot be archived.
-
-    Parameters
-    ----------
-    project:
-        The project to archive.
-    """
-    settings.client().projects.archive(project)
-    note(f"[dim]{project} is archived[/dim]")