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

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

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: xoople-cli
-Version: 0.4.0
+Version: 0.6.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.6.0
+Requires-Dist: xoople-sdk>=0.8.0
 Requires-Dist: cyclopts>=4.18,<5
 Requires-Dist: rich>=13.7
 Requires-Python: >=3.12
@@ -31,13 +31,14 @@ output pipes into `jq`.
 
 | Group | Commands |
 | --- | --- |
-| `analyses` | `list` `get` `create` `update` `cancel` `estimate` |
+| `analyses` | `list` `get` `create` `update` `cancel` `delete` `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` |
+| `questions` | `list` `show` `ask` |
 | `access` | `me` `token` `features` |
 | `auth` | `login` `logout` `status` |
 
@@ -89,11 +90,13 @@ 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 catalog designs --product tabular_time_series --json | jq '.[0].spec_fragment | {product: "tabular_time_series", period: {start: "2024-01-01", end: "2024-06-30"}, aoi: [-1.5, 52.0, -1.0, 52.5], spatial_partition: {type: "h3", target_cells: 5000}, measures}' > spec.json
 $ xoople analyses create -f spec.json --display-name "South Wales NDVI" --wait
 ```
 
+A design's `spec_fragment` holds only what to measure, so the `jq` filter adds the
+product, period, area and grid around its `measures`. The cadence defaults to monthly.
+
 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`.
@@ -105,4 +108,6 @@ non-zero if it does not reach `COMPLETE`.
 `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.
+`14` the analysis was deleted · `15` the view a question reads is still
+being built, ask again shortly · `16` that view's last build failed, refresh
+it explicitly; `17` the project was deleted.

{xoople_cli-0.4.0 → xoople_cli-0.6.0}/README.md

@@ -16,13 +16,14 @@ output pipes into `jq`.
 
 | Group | Commands |
 | --- | --- |
-| `analyses` | `list` `get` `create` `update` `cancel` `estimate` |
+| `analyses` | `list` `get` `create` `update` `cancel` `delete` `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` |
+| `questions` | `list` `show` `ask` |
 | `access` | `me` `token` `features` |
 | `auth` | `login` `logout` `status` |
 
@@ -74,11 +75,13 @@ 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 catalog designs --product tabular_time_series --json | jq '.[0].spec_fragment | {product: "tabular_time_series", period: {start: "2024-01-01", end: "2024-06-30"}, aoi: [-1.5, 52.0, -1.0, 52.5], spatial_partition: {type: "h3", target_cells: 5000}, measures}' > spec.json
 $ xoople analyses create -f spec.json --display-name "South Wales NDVI" --wait
 ```
 
+A design's `spec_fragment` holds only what to measure, so the `jq` filter adds the
+product, period, area and grid around its `measures`. The cadence defaults to monthly.
+
 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`.
@@ -90,4 +93,6 @@ non-zero if it does not reach `COMPLETE`.
 `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.
+`14` the analysis was deleted · `15` the view a question reads is still
+being built, ask again shortly · `16` that view's last build failed, refresh
+it explicitly; `17` the project was deleted.

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

@@ -1,6 +1,6 @@
 [project]
 name = "xoople-cli"
-version = "0.4.0"
+version = "0.6.0"
 description = "Command-line interface for the Xoople Products API."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "xoople-sdk>=0.6.0",
+    "xoople-sdk>=0.8.0",
     "cyclopts>=4.18,<5",
     "rich>=13.7",
 ]
@@ -23,7 +23,7 @@ xoople = "xoople.cli.main:main"
 Homepage = "https://xoople.com"
 
 [build-system]
-requires = ["uv_build>=0.11.6,<0.12"]
+requires = ["uv_build>=0.13.0,<0.14"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

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

@@ -1,6 +1,6 @@
 [project]
 name = "xoople-cli"
-version = "0.4.0"
+version = "0.6.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.6.0",
+  "xoople-sdk>=0.8.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
@@ -29,7 +29,7 @@ xoople = "xoople.cli.main:main"
 Homepage = "https://xoople.com"
 
 [build-system]
-requires = ["uv_build>=0.11.6,<0.12"]
+requires = ["uv_build>=0.13.0,<0.14"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

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

@@ -5,6 +5,7 @@ from typing import Annotated, Protocol
 from cyclopts import Parameter
 from xoople.cli import _ciam
 from xoople.cli._errors import UsageError
+from xoople.cli._version import version as cli_version
 from xoople.sdk import Config, CredentialProvider, XoopleClient
 from xoople.sdk import session as session_file
 from xoople.sdk.auth import (
@@ -108,5 +109,6 @@ def build_client(credentials: Credentials) -> XoopleClient:
             credentials=_credential_provider(credentials),
             timeout=credentials.timeout,
             max_retries=credentials.max_retries,
+            user_agent_prefix=f"xoople-cli/{cli_version()}",
         )
     )

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

@@ -1,3 +1,4 @@
+from rich.markup import escape
 from xoople.cli._output import note
 from xoople.sdk import errors
 
@@ -6,6 +7,7 @@ EXIT_CODES: dict[type[errors.XoopleError], int] = {
     errors.PermissionDeniedError: 4,
     # Before its parent: `exit_code` takes the first class the error is an instance of.
     errors.AnalysisDeletedError: 14,
+    errors.ProjectDeletedError: 17,
     errors.NotFoundError: 5,
     errors.BadRequestError: 6,
     errors.ValidationError: 6,
@@ -20,6 +22,8 @@ _FALLBACK_EXIT = 1
 USAGE_EXIT = 2
 FAILED_RUN_EXIT = 12
 WAIT_TIMEOUT_EXIT = 13
+QUESTION_COMPUTING_EXIT = 15
+QUESTION_FAILED_EXIT = 16
 
 
 class CliError(Exception):
@@ -56,6 +60,18 @@ class WaitTimeout(CliError):
     exit_code = WAIT_TIMEOUT_EXIT
 
 
+class QuestionComputing(CliError):
+    """The view a question reads is still being built; ask again shortly."""
+
+    exit_code = QUESTION_COMPUTING_EXIT
+
+
+class QuestionFailed(CliError):
+    """The last build of the view a question reads failed; refresh it explicitly."""
+
+    exit_code = QUESTION_FAILED_EXIT
+
+
 def exit_code(exc: errors.XoopleError) -> int:
     for cls, code in EXIT_CODES.items():
         if isinstance(exc, cls):
@@ -64,10 +80,11 @@ def exit_code(exc: errors.XoopleError) -> int:
 
 
 def _describe(exc: errors.XoopleError) -> str:
+    # The API text is data, not markup: a detail that echoes a cell can read like `[red]`.
     if isinstance(exc, errors.XoopleAPIError):
-        trace = f" [dim](trace {exc.trace_id})[/dim]" if exc.trace_id else ""
-        return f"[red]error[/red] {exc.status} {exc.code}: {exc.message}{trace}"
-    return f"[red]error[/red] {exc}"
+        trace = f" [dim](trace {escape(str(exc.trace_id))})[/dim]" if exc.trace_id else ""
+        return f"[red]error[/red] {exc.status} {escape(str(exc.code))}: {escape(str(exc.message))}{trace}"
+    return f"[red]error[/red] {escape(str(exc))}"
 
 
 def report(exc: errors.XoopleError | CliError) -> int:
@@ -80,5 +97,5 @@ def report(exc: errors.XoopleError | CliError) -> int:
     if isinstance(exc, errors.XoopleError):
         note(_describe(exc))
         return exit_code(exc)
-    note(f"[red]error[/red] {exc}")
+    note(f"[red]error[/red] {escape(str(exc))}")
     return exc.exit_code

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

@@ -4,6 +4,7 @@ from collections.abc import Iterable, Sequence
 from pydantic import BaseModel
 from rich.console import Console
 from rich.table import Table
+from rich.text import Text
 
 type Column = tuple[str, str]
 
@@ -103,6 +104,36 @@ def emit_one(model: BaseModel, fields: Sequence[Column], *, as_json: bool) -> No
     _console.print(table)
 
 
+def emit_grid(
+    model: BaseModel,
+    headers: Sequence[str],
+    rows: Iterable[Sequence[object]],
+    *,
+    as_json: bool,
+) -> None:
+    """Render positional rows under their headers: raw JSON of the whole
+    response, or a table whose columns come from the data, not a declared list."""
+    if as_json:
+        _raw_json(model.model_dump(mode="json", by_alias=True))
+        return
+    items = [list(row) for row in rows]
+    if not items:
+        _stderr.print("[dim]no rows[/dim]")
+        return
+    # Literal text throughout: a cell is customer data (a feature id can read
+    # like rich markup) and a measure keeps its full precision.
+    table = Table(box=None, pad_edge=False, header_style="bold")
+    for header in headers:
+        table.add_column(Text(header), overflow="ellipsis", no_wrap=True)
+    for row in items:
+        table.add_row(*(Text(_grid_cell(value)) for value in row))
+    _console.print(table)
+
+
+def _grid_cell(value: object) -> str:
+    return repr(value) if isinstance(value, float) else _scalar(value)
+
+
 def emit_model(model: BaseModel, *, as_json: bool) -> None:
     """Render every declared field of a single resource.
 
@@ -114,6 +145,30 @@ def emit_model(model: BaseModel, *, as_json: bool) -> None:
     emit_one(model, fields, as_json=as_json)
 
 
+def emit_rows(headers: Sequence[str], rows: Iterable[Sequence[object]]) -> None:
+    """Render rows that are already positional — a question's answer, say.
+
+    Goes through the same console as `emit`, so piped output does not depend
+    on the width of the terminal that launched it.
+    """
+    table = Table(box=None, pad_edge=False, header_style="bold")
+    for header in headers:
+        table.add_column(header, overflow="ellipsis", no_wrap=True)
+    for row in rows:
+        table.add_row(*(_scalar(cell) for cell in row))
+    _console.print(table)
+
+
+def emit_pairs(pairs: Iterable[tuple[str, object]]) -> None:
+    """Render name/value lines for values that are not a model's fields."""
+    table = Table(box=None, pad_edge=False, show_header=False)
+    table.add_column(style="bold")
+    table.add_column(overflow="fold")
+    for name, value in pairs:
+        table.add_row(name, _scalar(value))
+    _console.print(table)
+
+
 def heading(text: str) -> None:
     """A section label for a command that prints more than one table."""
     _console.print(f"\n[bold]{text}[/bold]")

{xoople_cli-0.4.0 → xoople_cli-0.6.0}/src/xoople/cli/access.py

@@ -8,7 +8,7 @@ from xoople.cli._output import emit, emit_model
 
 app = App(
     name="access",
-    help="Delta Sharing credentials and feature flags for your account.",
+    help="Delta Sharing credentials and preview features for your account.",
 )
 
 
@@ -22,7 +22,7 @@ class _FlagRow(BaseModel):
 
 @app.command(name="me")
 def me(*, settings: SettingsParam) -> None:
-    """Show your Delta Sharing recipient and the share it reads."""
+    """Show your Delta Sharing recipient and the schema of your org's shared tables."""
     emit_model(settings.client().data_access.me(), as_json=settings.as_json)
 
 
@@ -67,7 +67,7 @@ def rotate_token(
 
 @app.command(name="features")
 def features(*, settings: SettingsParam) -> None:
-    """Show which feature flags are on for you, and why."""
+    """Show which preview features are on for you, and why."""
     result = settings.client().features.get()
     if settings.as_json:
         emit_model(result, as_json=True)
@@ -78,6 +78,6 @@ def features(*, settings: SettingsParam) -> None:
     ]
     emit(
         flags,
-        [("FLAG", "flag"), ("ON", "value"), ("REASON", "reason")],
+        [("PREVIEW FEATURE", "flag"), ("ON", "value"), ("REASON", "reason")],
         as_json=False,
     )

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

@@ -1,5 +1,5 @@
 from pathlib import Path
-from typing import Annotated, Literal
+from typing import Annotated
 
 from cyclopts import App, Parameter
 from xoople.cli._context import SettingsParam, at_least_one
@@ -29,7 +29,8 @@ FIELDS = [
     ("UID", "uid"),
     ("Display name", "display_name"),
     ("Product", "product"),
-    ("Product version", "product_version"),
+    ("Schema version", "schema_version"),
+    ("Output schema outdated", "output_schema_outdated"),
     ("State", "state"),
     ("State message", "state_message"),
     ("Owner", "owner"),
@@ -178,46 +179,19 @@ 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.
+@app.command(name="delete")
+def delete(analysis: str, *, settings: SettingsParam) -> None:
+    """Delete a settled analysis and its outputs.
 
-    Only the owner may unshare; repeating the call changes nothing.
+    Removal runs in the background, so the analysis shows as DELETING. Once it
+    finishes, `analyses get` exits with the deleted-analysis code.
 
     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.
+        The analysis to delete. Needs its owner; cancel a running analysis first.
     """
-    settings.client().analyses.unshare(analysis, share)
-    note(f"[dim]{analysis} is no longer shared with {share}[/dim]")
+    emit_one(settings.client().analyses.delete(analysis), FIELDS, as_json=settings.as_json)
 
 
 @app.command(name="run-again")

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

@@ -17,7 +17,7 @@ def products(*, settings: SettingsParam) -> None:
         [
             ("ID", "product_id"),
             ("NAME", "display_name"),
-            ("VERSION", "version"),
+            ("SCHEMA VERSION", "schema_version"),
             ("LIFECYCLE", "lifecycle"),
             ("OUTPUTS", "output_kinds"),
         ],
@@ -121,7 +121,7 @@ def cloud_mask_presets(*, settings: SettingsParam) -> None:
 
 @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.
+    """List the starting-point analysis designs. Their `spec_fragment` seeds measures or bands only.
 
     Parameters
     ----------

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

@@ -10,6 +10,7 @@ from xoople.cli import (
     outputs,
     packages,
     projects,
+    questions,
     runs,
     schedules,
     usage,
@@ -56,6 +57,7 @@ def create_app(
     app.command(events.app)
     app.command(usage.app)
     app.command(catalog.app)
+    app.command(questions.app)
     app.command(access.app)
     app.command(auth.app)
 

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

@@ -2,7 +2,7 @@ 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
+from xoople.cli._output import emit, emit_grid, emit_model, note
 
 app = App(
     name="outputs",
@@ -94,6 +94,45 @@ def summary(analysis: str, output: str, *, settings: SettingsParam) -> None:
     )
 
 
+@app.command(name="preview")
+def preview(
+    analysis: str,
+    output: str,
+    *,
+    settings: SettingsParam,
+    limit: Annotated[int | None, Parameter(validator=at_least_one)] = None,
+    columns: str | None = None,
+) -> None:
+    """Show the first rows of an output's table, in no particular order.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis the output belongs to.
+    output:
+        The output whose rows to show.
+    limit:
+        Rows to show, up to 100 (also the default). For every row, read the
+        table instead.
+    columns:
+        Comma-separated column names to show, in this order; omit for every column.
+    """
+    result = settings.client().analyses.outputs.get_preview(
+        analysis,
+        output,
+        limit=limit,
+        columns=[name.strip() for name in columns.split(",")] if columns is not None else None,
+    )
+    emit_grid(
+        result,
+        [column.name for column in result.columns],
+        result.rows,
+        as_json=settings.as_json,
+    )
+    if result.truncated and not settings.as_json:
+        note(f"[dim]showing the first {len(result.rows)} rows; the table holds more[/dim]")
+
+
 @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.

{xoople_cli-0.4.0 → xoople_cli-0.6.0}/src/xoople/cli/packages.py

@@ -2,7 +2,7 @@ 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
+from xoople.cli._output import emit, emit_model, note
 
 app = App(
     name="packages",
@@ -90,3 +90,25 @@ def access_url(
         analysis, package, access_ttl_hours=access_ttl_hours
     )
     emit_model(result, as_json=settings.as_json)
+
+
+@app.command(name="delete")
+def delete(analysis: str, package: str, *, settings: SettingsParam) -> None:
+    """Delete a package and its files; the source table and other packages stay.
+
+    Cleanup runs in the background, so the package shows as DELETING until
+    `packages get` reports DELETED. Run this again on a DELETE_FAILED package
+    to retry it.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis the package belongs to.
+    package:
+        The package to delete. Needs its owner; a package still being built cannot be deleted.
+    """
+    result = settings.client().analyses.packages.delete(analysis, package)
+    if result is None:
+        note(f"[dim]{package} is already deleted[/dim]")
+        return
+    emit_model(result, as_json=settings.as_json)

xoople_cli-0.6.0/src/xoople/cli/questions.py

@@ -0,0 +1,209 @@
+"""Browse the question catalogue and ask one of a completed output."""
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+from xoople.cli._context import SettingsParam
+from xoople.cli._errors import CliError, QuestionComputing, QuestionFailed, UsageError
+from xoople.cli._output import emit, emit_model, emit_pairs, emit_rows, heading, note
+from xoople.sdk import XoopleClient
+from xoople.sdk.answers import QuestionAnswer
+
+app = App(
+    name="questions",
+    help="Browse the questions an output can answer, and ask one.",
+)
+
+_CATALOG_COLUMNS = [
+    ("ID", "id"),
+    ("QUESTION", "question"),
+    ("CATEGORY", "category"),
+    ("RESULT", "result_kind"),
+    ("MEASURE", "requires_measure"),
+]
+
+
+@app.command(name="list")
+def list_questions(
+    *,
+    settings: SettingsParam,
+    analysis: str | None = None,
+    output: str | None = None,
+    category: list[str] | None = None,
+    available: bool = False,
+) -> None:
+    """List the questions that can be asked.
+
+    Without an analysis this is the product catalogue, which answers before
+    anything has run. With one, each entry says whether that output can
+    answer it and what to do when it cannot.
+
+    Parameters
+    ----------
+    analysis:
+        Narrow the catalogue to one analysis's output.
+    output:
+        Which output of that analysis; defaults to its primary table.
+    category:
+        Only these categories. Repeat to pass several.
+    available:
+        With an analysis, hide the questions this output cannot answer.
+    """
+    client = settings.client()
+    if analysis is None:
+        result = client.questions.list(category=category)
+        emit(result.questions, _CATALOG_COLUMNS, as_json=settings.as_json)
+        return
+
+    bound = client.analyses.outputs.list_questions(
+        analysis, _resolve_output(client, analysis, output)
+    )
+    entries = [
+        entry
+        for entry in bound.questions or []
+        if (not available or entry.available)
+        and (not category or entry.question.category in category)
+    ]
+    if settings.as_json:
+        emit_model(bound.model_copy(update={"questions": entries}), as_json=True)
+        return
+    note(
+        f"measures: {', '.join(bound.measures or [])} · "
+        f"grid: {bound.grid or '-'} · summary: {bound.summary_status} · "
+        f"grid build: {bound.sampler_status}"
+    )
+    if not entries:
+        note("no matching questions")
+        return
+    emit_rows(
+        ("ID", "QUESTION", "ASKABLE", "WHY NOT"),
+        [
+            (
+                entry.question.id,
+                entry.question.question,
+                entry.available,
+                entry.unavailable_reason,
+            )
+            for entry in entries
+        ],
+    )
+
+
+@app.command(name="show")
+def show(question: str, *, settings: SettingsParam) -> None:
+    """Show one question's parameters and what it needs an output to carry.
+
+    Parameters
+    ----------
+    question:
+        The question id, as `questions list` prints it.
+    """
+    result = settings.client().questions.list()
+    entry = next((item for item in result.questions or [] if item.id == question), None)
+    if entry is None:
+        raise CliError(f"unknown question: {question}")
+    if settings.as_json:
+        emit_model(entry, as_json=True)
+        return
+    emit_model(entry, as_json=False)
+    heading("parameters")
+    emit(
+        entry.parameters or [],
+        [
+            ("NAME", "name"),
+            ("TYPE", "type"),
+            ("REQUIRED", "required"),
+            ("DEFAULT", "default"),
+            ("DESCRIPTION", "description"),
+        ],
+        as_json=False,
+    )
+
+
+@app.command(name="ask")
+def ask(
+    analysis: str,
+    question: str,
+    *,
+    settings: SettingsParam,
+    output: str | None = None,
+    param: Annotated[list[str] | None, Parameter(name="--param")] = None,
+) -> None:
+    """Ask one question of an analysis's output.
+
+    Parameters
+    ----------
+    analysis:
+        The analysis whose output to ask about.
+    question:
+        The question id, as `questions list` prints it.
+    output:
+        Which output to ask about; defaults to the analysis's primary table.
+    param:
+        A `name=value` parameter. Repeat for several; `questions show` lists
+        what each question accepts.
+    """
+    client = settings.client()
+    answer = client.analyses.outputs.ask(
+        analysis,
+        _resolve_output(client, analysis, output),
+        question,
+        **_parameters(param or []),
+    )
+    if settings.as_json:
+        emit_model(answer.response, as_json=True)
+    else:
+        _print_answer(answer)
+    # The payload is out either way; the exit code says it is not an answer yet.
+    if answer.computing:
+        raise QuestionComputing(answer.response.answer)
+    if answer.failed:
+        raise QuestionFailed(answer.response.answer)
+
+
+def _print_answer(answer: QuestionAnswer) -> None:
+    response = answer.response
+    if response.status != "ANSWERED":
+        return
+    note(response.answer)
+    if response.rows:
+        emit_rows(
+            [
+                f"{column.name} ({column.unit})" if column.unit else column.name
+                for column in response.columns or []
+            ],
+            response.rows,
+        )
+    if response.totals:
+        heading("totals")
+        emit_pairs(response.totals.items())
+    for caveat in response.caveats or []:
+        note(f"[yellow]note[/yellow] {caveat}")
+
+
+def _parameters(values: list[str]) -> dict[str, bool | int | float | str | None]:
+    """`name=value` pairs, sent as typed.
+
+    The question's schema converts and validates server-side, so a number
+    travels as the text it was typed as and `period=2024` stays a string.
+    Only a boolean needs reading here, because the schema takes no text for one.
+    """
+    parsed: dict[str, bool | int | float | str | None] = {}
+    for item in values:
+        name, separator, raw = item.partition("=")
+        if not separator or not name:
+            raise UsageError(f"--param expects name=value, got {item!r}")
+        parsed[name] = raw.lower() == "true" if raw.lower() in ("true", "false") else raw
+    return parsed
+
+
+def _resolve_output(client: XoopleClient, analysis: str, output: str | None) -> str:
+    """The named output, or the analysis's only table output."""
+    if output is not None:
+        return output
+    outputs = [
+        item for item in client.analyses.outputs.list(analysis) if item.kind == "delta_table"
+    ]
+    if not outputs:
+        raise CliError(f"analysis {analysis} has no table output to ask about")
+    return str(outputs[0].uid)