xoople-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{xoople_cli-0.1.0 → xoople_cli-0.3.0}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: xoople-cli
-Version: 0.1.0
+Version: 0.3.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.2.0
+Requires-Dist: xoople-sdk>=0.5.0
 Requires-Dist: cyclopts>=4.18,<5
 Requires-Dist: rich>=13.7
-Requires-Dist: xoople-sdk[entra]>=0.1.0 ; extra == 'entra'
+Requires-Dist: xoople-sdk[entra]>=0.5.0 ; extra == 'entra'
 Requires-Python: >=3.12
 Project-URL: Homepage, https://xoople.com
 Provides-Extra: entra
@@ -41,6 +41,26 @@ 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
+neither `--token` nor `--entra-scope` is given, and refreshes it when the
+access token is close to expiry.
+
+```console
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_CIAM_CLIENT_ID=client_...
+$ xoople auth login
+$ xoople analyses list
+```
+
+`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.
 
 ## Submitting an analysis
 
@@ -48,7 +68,7 @@ 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 '.designs[0].spec_fragment' > spec.json
+$ 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
 ```
@@ -59,7 +79,8 @@ 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.

{xoople_cli-0.1.0 → xoople_cli-0.3.0}/README.md

@@ -24,6 +24,26 @@ 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
+neither `--token` nor `--entra-scope` is given, and refreshes it when the
+access token is close to expiry.
+
+```console
+$ export XOOPLE_API_URL=https://api.xoople.com XOOPLE_CIAM_CLIENT_ID=client_...
+$ xoople auth login
+$ xoople analyses list
+```
+
+`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.
 
 ## Submitting an analysis
 
@@ -31,7 +51,7 @@ 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 '.designs[0].spec_fragment' > spec.json
+$ 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
 ```
@@ -42,7 +62,8 @@ 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.

{xoople_cli-0.1.0 → xoople_cli-0.3.0}/pyproject.toml

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

{xoople_cli-0.1.0 → xoople_cli-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xoople-cli"
-version = "0.1.0"
+version = "0.3.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.2.0",
+  "xoople-sdk>=0.5.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
@@ -26,7 +26,7 @@ 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.1.0",
+  "xoople-sdk[entra]>=0.5.0",
 ]
 
 [project.scripts]

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

@@ -0,0 +1,190 @@
+"""The browser half of a CIAM sign-in, and where the session is stored.
+
+The SDK owns the protocol. It holds the endpoints, PKCE, both grants and the
+refresh. This module holds what needs a terminal. It opens a browser, binds the
+loopback port and writes the session file.
+"""
+
+import os
+import secrets
+import tempfile
+import time
+import urllib.parse
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Protocol, Self
+
+from pydantic import ValidationError
+from xoople.cli._errors import LoginFailed
+from xoople.sdk.auth import (
+    CiamUserSession,
+    ciam_authorize_url,
+    ciam_exchange_code,
+    ciam_pkce_pair,
+)
+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."""
+
+_CALLBACK_TIMEOUT_SECONDS = 300
+
+_DONE_PAGE = b"<html><body><p>Xoople sign-in is complete. Close this tab.</p></body></html>"
+
+
+class _Listener(Protocol):
+    def __call__(self, redirect_uri: str, timeout: float) -> dict[str, str]: ...
+
+
+class _Exchanger(Protocol):
+    def __call__(self, *, client_id: str, code: str, verifier: str) -> CiamUserSession: ...
+
+
+@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) -> Self:
+        if not client_id:
+            raise LoginFailed("no CIAM client: pass --ciam-client-id or set XOOPLE_CIAM_CLIENT_ID")
+        return cls(client_id=client_id, redirect_uri=redirect_uri or DEFAULT_REDIRECT_URI)
+
+
+def session_path() -> Path:
+    """Where the session file lives, honouring `XDG_CONFIG_HOME`."""
+    root = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(root) if root else Path.home() / ".config"
+    return base / "xoople" / "session.json"
+
+
+def read_session(path: Path | None = None) -> CiamUserSession | None:
+    """The stored session, or None when there is none this CLI can read."""
+    target = path or session_path()
+    try:
+        raw = target.read_bytes()
+    except OSError:
+        return None
+    try:
+        return CiamUserSession.model_validate_json(raw)
+    except ValidationError:
+        return None
+
+
+def write_session(session: CiamUserSession, path: Path | None = None) -> Path:
+    """Store the session so only this user can read it.
+
+    The mode argument of `os.open` applies to a new file only, so a rewrite of
+    an existing permissive file would keep its mode. This writes a private
+    temporary file and renames it over the target.
+    """
+    target = path or session_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    handle, temporary = tempfile.mkstemp(dir=target.parent, prefix=".session-")
+    try:
+        os.fchmod(handle, 0o600)
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            stream.write(session.model_dump_json())
+        # Rename is atomic within one directory, so a reader never sees a
+        # half-written session.
+        os.replace(temporary, target)
+    except BaseException:
+        Path(temporary).unlink(missing_ok=True)
+        raise
+    return target
+
+
+def clear_session(path: Path | None = None) -> bool:
+    """Remove the stored session. False when there was nothing to remove."""
+    target = path or session_path()
+    try:
+        target.unlink()
+    except OSError:
+        return False
+    return True
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """Reads the query off one browser redirect and answers with a closing page."""
+
+    captured: dict[str, str]
+    callback_path: str
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlsplit(self.path)
+        if parsed.path != self.callback_path:
+            self.send_error(404)
+            return
+        for key, values in urllib.parse.parse_qs(parsed.query).items():
+            self.captured[key] = values[0]
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(_DONE_PAGE)))
+        self.end_headers()
+        self.wfile.write(_DONE_PAGE)
+
+    def log_message(self, format: str, *args: object) -> None:
+        del format, args  # The server must not write to the CLI's streams.
+
+
+def await_callback(redirect_uri: str, timeout: float) -> dict[str, str]:
+    """Serve the redirect URI until the browser returns, and give back its query."""
+    parsed = urllib.parse.urlsplit(redirect_uri)
+    if parsed.hostname is None or parsed.port is None:
+        raise LoginFailed(f"redirect URI needs an explicit host and port: {redirect_uri}")
+    captured: dict[str, str] = {}
+    handler = type(
+        "_BoundCallbackHandler",
+        (_CallbackHandler,),
+        {"captured": captured, "callback_path": parsed.path or "/"},
+    )
+    deadline = time.monotonic() + timeout
+    with HTTPServer((parsed.hostname, parsed.port), handler) as server:
+        # A browser also asks for /favicon.ico, so serve until the callback lands.
+        while not captured and time.monotonic() < deadline:
+            server.timeout = max(1.0, deadline - time.monotonic())
+            server.handle_request()
+    if not captured:
+        raise LoginFailed("the browser did not return a sign-in result in time")
+    return captured
+
+
+def login(
+    config: CiamConfig,
+    *,
+    announce: Callable[[str], None],
+    listener: _Listener = await_callback,
+    open_browser: Callable[[str], bool] = webbrowser.open,
+    exchange: _Exchanger = ciam_exchange_code,
+    callback_timeout: float = _CALLBACK_TIMEOUT_SECONDS,
+) -> CiamUserSession:
+    """Run one browser login and return the session it produced."""
+    verifier, challenge = ciam_pkce_pair()
+    state = secrets.token_urlsafe(16)
+    url = ciam_authorize_url(
+        client_id=config.client_id,
+        redirect_uri=config.redirect_uri,
+        challenge=challenge,
+        state=state,
+    )
+    announce(url)
+    open_browser(url)
+    captured = listener(config.redirect_uri, callback_timeout)
+    if "error" in captured:
+        raise LoginFailed(f"CIAM refused the sign-in: {captured['error']}")
+    if captured.get("state") != state:
+        raise LoginFailed("the sign-in result does not match this request")
+    code = captured.get("code")
+    if not code:
+        raise LoginFailed("the sign-in result carries no authorization code")
+    try:
+        return exchange(client_id=config.client_id, code=code, verifier=verifier)
+    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.1.0 → xoople_cli-0.3.0}/src/xoople/cli/_context.py

@@ -1,11 +1,17 @@
 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.auth import (
+    CiamUserCredentials,
+    CiamUserSession,
+    EntraCredential,
+    StaticToken,
+)
 
 
 @dataclass(frozen=True)
@@ -15,16 +21,26 @@ 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
 
 
-# How Credentials become a client — swapped for a fake in tests.
+# The client factory is swapped for a fake in tests.
 type ClientFactory = Callable[[Credentials], XoopleClient]
 
-# Every command declares this keyword-only parameter; the meta-app launcher in
-# ``main.py`` injects the resolved ``Settings`` via ``parse=False``, so commands
-# stay plain functions and tests drive them over a fake transport.
+
+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)]
 
 
@@ -46,6 +62,7 @@ class Settings:
 
     credentials: Credentials
     factory: ClientFactory
+    login: LoginRunner = _ciam.login
     as_json: bool = False
     _client: XoopleClient | None = field(default=None, repr=False)
 
@@ -60,12 +77,24 @@ class Settings:
             self._client = None
 
 
+def _persist_session(session: CiamUserSession) -> None:
+    _ciam.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 = _ciam.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, set XOOPLE_TOKEN, "
+        "or pass --entra-scope"
+    )
 
 
 def build_client(credentials: Credentials) -> XoopleClient:

{xoople_cli-0.1.0 → xoople_cli-0.3.0}/src/xoople/cli/_errors.py

@@ -14,10 +14,7 @@ EXIT_CODES: dict[type[errors.XoopleError], int] = {
     errors.XoopleResponseError: 11,
 }
 _FALLBACK_EXIT = 1
-# ``CliError`` with no specific subclass falls back to 1. Nothing raises a bare
-# ``CliError`` today; every CLI-detected outcome has its own subclass below.
-# Outcomes the CLI decides rather than the API. Kept here with the status map so
-# the README's exit-code table has one source.
+# Generic CLI errors fall back to 1; CLI-only outcomes use the codes below.
 USAGE_EXIT = 2
 FAILED_RUN_EXIT = 12
 WAIT_TIMEOUT_EXIT = 13
@@ -35,6 +32,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.1.0 → xoople_cli-0.3.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.1.0 → xoople_cli-0.3.0}/src/xoople/cli/access.py

@@ -1,3 +1,6 @@
+import sys
+from typing import Literal
+
 from cyclopts import App
 from pydantic import BaseModel
 from xoople.cli._context import SettingsParam
@@ -24,11 +27,44 @@ def me(*, settings: SettingsParam) -> None:
 
 
 @app.command(name="token")
-def token(*, settings: SettingsParam) -> None:
-    """Print your Delta Sharing bearer token and host."""
+def token(
+    *,
+    settings: SettingsParam,
+    format: Literal["json", "share"] = "json",
+) -> None:
+    """Print your Delta Sharing bearer token and host.
+
+    With --format share, write the downloadable .share profile to stdout —
+    pipe to a file for any Delta Sharing client that reads its credentials
+    from it.
+    """
+    if format == "share":
+        # Write the served bytes, not decoded text: a text stream applies the
+        # locale encoding and newline translation, so `> profile.share` would
+        # not be byte-for-byte the server's.
+        sys.stdout.buffer.write(settings.client().data_access.share_profile())
+        sys.stdout.buffer.flush()
+        return
     emit_model(settings.client().data_access.token(), as_json=settings.as_json)
 
 
+@app.command(name="rotate-token")
+def rotate_token(
+    *,
+    settings: SettingsParam,
+    existing_token_expire_in_seconds: int = 3600,
+) -> None:
+    """Issue a fresh Delta Sharing token, keeping your existing share grants.
+
+    The superseded token keeps working for --existing-token-expire-in-seconds,
+    so running jobs can pick up the new one. Pass 0 to revoke it now.
+    """
+    emit_model(
+        settings.client().data_access.rotate_token(existing_token_expire_in_seconds),
+        as_json=settings.as_json,
+    )
+
+
 @app.command(name="features")
 def features(*, settings: SettingsParam) -> None:
     """Show which feature flags are on for you, and why."""

{xoople_cli-0.1.0 → xoople_cli-0.3.0}/src/xoople/cli/analyses.py

@@ -1,5 +1,5 @@
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Literal
 
 from cyclopts import App, Parameter
 from xoople.cli._context import SettingsParam, at_least_one
@@ -39,6 +39,16 @@ FIELDS = [
     ("Updated", "update_time"),
 ]
 
+STATUS_FIELDS = [
+    ("Name", "name"),
+    ("UID", "uid"),
+    ("State", "state"),
+    ("State message", "state_message"),
+    ("Retries", "retry_count"),
+    ("Created", "create_time"),
+    ("Updated", "update_time"),
+]
+
 _SPEC_FILE = Parameter(name=["--spec-file", "-f"], allow_leading_hyphen=True)
 
 
@@ -74,6 +84,21 @@ def get(analysis: str, *, settings: SettingsParam) -> None:
     emit_one(settings.client().analyses.get(analysis), FIELDS, as_json=settings.as_json)
 
 
+@app.command(name="status")
+def status(analysis: str, *, settings: SettingsParam) -> None:
+    """Show how far one analysis has got, without its settings.
+
+    Cheaper than `get` on both ends: it reads none of the stored request, so it
+    is the one to call in a loop.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis to show.
+    """
+    emit_one(settings.client().analyses.status(analysis), STATUS_FIELDS, as_json=settings.as_json)
+
+
 @app.command(name="create")
 def create(
     *,
@@ -148,6 +173,101 @@ def cancel(analysis: str, *, settings: SettingsParam) -> None:
     emit_one(settings.client().analyses.cancel(analysis), FIELDS, as_json=settings.as_json)
 
 
+@app.command(name="share")
+def share(
+    analysis: str,
+    *,
+    settings: SettingsParam,
+    scope: Literal["org"] = "org",
+) -> None:
+    """Let your organisation read one analysis.
+
+    Anyone in your organisation can then open it by name. It stays out of their
+    listings, and the share grants them no reuse action and no access to the
+    underlying data. Only the owner may share; repeating the call changes
+    nothing.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis to share.
+    scope:
+        Who to share with. Only your own organisation may be named.
+    """
+    emit_one(settings.client().analyses.share(analysis, scope), FIELDS, as_json=settings.as_json)
+
+
+@app.command(name="unshare")
+def unshare(analysis: str, *, settings: SettingsParam, share: str = "org") -> None:
+    """Revoke one grant on an analysis.
+
+    Only the owner may unshare; repeating the call changes nothing.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis to revoke a grant on.
+    share:
+        Which grant to revoke. `org` names your whole organisation, the only
+        audience an analysis can be shared with today.
+    """
+    settings.client().analyses.unshare(analysis, share)
+    note(f"[dim]{analysis} is no longer shared with {share}[/dim]")
+
+
+@app.command(name="run-again")
+def run_again(
+    analysis: str,
+    *,
+    settings: SettingsParam,
+    idempotency_key: str | None = None,
+    wait: bool = False,
+    poll_interval: float = 5.0,
+    wait_timeout: float | None = None,
+) -> None:
+    """Run a settled analysis again as a new related analysis.
+
+    Settled means completed, failed or cancelled; a run still under way cannot
+    be repeated.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis whose settings to repeat.
+    idempotency_key:
+        Reuse a previous key to replay the action instead of repeating it.
+    wait:
+        Poll the new analysis's newest run until it reaches a terminal state.
+    poll_interval:
+        Seconds between polls while waiting.
+    wait_timeout:
+        Give up waiting after this many seconds.
+    """
+    child = settings.client().analyses.run_again(analysis, idempotency_key=idempotency_key)
+    if not wait:
+        emit_one(child, FIELDS, as_json=settings.as_json)
+        return
+    note(f"[dim]submitted {child.uid}; waiting for the initial run[/dim]")
+    run = wait_for_run(
+        settings.client(), child.uid, poll_interval=poll_interval, timeout=wait_timeout
+    )
+    emit_one(run, RUN_FIELDS, as_json=settings.as_json)
+    if run.state is not models.RunState.COMPLETE:
+        raise RunFailed(f"run {run.uid} ended in {run.state}")
+
+
+@app.command(name="estimate-run-again")
+def estimate_run_again(analysis: str, *, settings: SettingsParam) -> None:
+    """Estimate running an analysis again, without submitting it.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis whose settings to price.
+    """
+    emit_model(settings.client().analyses.estimate_run_again(analysis), as_json=settings.as_json)
+
+
 @app.command(name="estimate")
 def estimate(*, settings: SettingsParam, spec_file: Annotated[Path, _SPEC_FILE]) -> None:
     """Estimate what a spec would cost, without submitting it.

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

@@ -0,0 +1,53 @@
+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
+
+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
+
+
+@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
+    )
+    note(f"Serving the sign-in callback on {config.redirect_uri}")
+    session = settings.login(config, announce=lambda url: note(f"Opening {url}"))
+    path = _ciam.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 _ciam.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 = _ciam.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.1.0 → xoople_cli-0.3.0}/src/xoople/cli/catalog.py

@@ -75,6 +75,51 @@ def measures(
         )
 
 
+@app.command(name="projections")
+def projections(*, settings: SettingsParam, bbox: str) -> None:
+    """List the output projections an area may be gridded on, most local first.
+
+    These are the only values `target_crs` accepts for this area. Omitting
+    `target_crs` grids on the area's UTM zone, which is never listed.
+
+    Parameters
+    ----------
+    bbox:
+        The area, as `min_lon,min_lat,max_lon,max_lat` in WGS84 degrees.
+    """
+    result = settings.client().catalog.suggest_projections(bbox=bbox)
+    emit(
+        result.projections,
+        [
+            ("CODE", "code"),
+            ("NAME", "display_name"),
+            ("TIER", "tier"),
+            ("SAME GRID AS AUTOMATIC", "same_grid_as_automatic"),
+            ("SCALE NOTE", "scale_note"),
+        ],
+        as_json=settings.as_json,
+    )
+
+
+@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.1.0 → xoople_cli-0.3.0}/src/xoople/cli/main.py

@@ -1,19 +1,38 @@
 from typing import Annotated
 
 from cyclopts import App, CycloptsError, Parameter
-from xoople.cli import access, analyses, catalog, events, outputs, runs, schedules, usage
-from xoople.cli._context import ClientFactory, Credentials, Settings, build_client
+from xoople.cli import (
+    access,
+    analyses,
+    auth,
+    catalog,
+    events,
+    outputs,
+    projects,
+    runs,
+    schedules,
+    usage,
+)
+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
 
 
-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) -> 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.
     """
     app = App(
         name="xoople",
@@ -21,6 +40,7 @@ def create_app(factory: ClientFactory = build_client) -> App:
         help="Command-line interface for the Xoople Products API.",
     )
     app.command(analyses.app)
+    app.command(projects.app)
     app.command(runs.app)
     app.command(outputs.app)
     app.command(schedules.app)
@@ -28,6 +48,7 @@ def create_app(factory: ClientFactory = build_client) -> App:
     app.command(usage.app)
     app.command(catalog.app)
     app.command(access.app)
+    app.command(auth.app)
 
     @app.meta.default
     def launcher(
@@ -35,6 +56,10 @@ def create_app(factory: ClientFactory = build_client) -> App:
         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,
@@ -50,6 +75,11 @@ def create_app(factory: ClientFactory = build_client) -> App:
         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`.
+        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:
@@ -67,10 +97,13 @@ def create_app(factory: ClientFactory = build_client) -> App:
                 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,
             as_json=json_output,
         )
         try:

{xoople_cli-0.1.0 → xoople_cli-0.3.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.3.0/src/xoople/cli/projects.py

@@ -0,0 +1,190 @@
+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,
+    )
+
+
+@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="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)