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

duckhaven_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to `duckhaven-cli` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions come from git tags
+(`duckhaven-cli-vX.Y.Z`).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-15
+
+### Changed
+
+- `dh sql` and the REPL ask the server to hold the submit for up to two seconds, so a quick
+  query finishes in one request instead of a submit and a poll. `--no-wait` still returns at
+  once. A server that predates the hold ignores it.
+- Ready for DuckHaven `api_version` 3: `DECIMAL` and wide integers, which it sends as
+  strings, print as before in table and CSV output and stay exact strings with
+  `--format json`.
+
+## [0.3.0] - 2026-10-13
+
+Brings the CLI up to date with the DuckHaven server's result cache, DuckLake catalogs,
+agent runtimes, worksheets and reshaped monitoring. Everything new needs a server that
+offers it; against an older one the command fails with that server's own error.
+
+### Added
+
+- **Result cache.** `--no-cache` on `dh sql`, `dh query run`, `dh session open` and
+  `dh session exec`, and `dh workspace update --result-cache/--no-result-cache` (owner
+  only). When a query was answered from the cache, `dh sql` and `dh session exec` say so on
+  stderr. The REPL is not cache-aware.
+- **Catalogs.** `dh catalog create --kind` (`iceberg_polaris` or `ducklake`),
+  `dh catalog kinds`, `dh catalog rotate-role`, and `dh catalog export list|create|cancel`
+  for copying a DuckLake catalog out as Iceberg. `dh admin catalog reconcile-roles` creates
+  any DuckLake database role that is missing (idempotent, deployment-wide).
+- **Runtimes.** `dh agent runtimes`, and `--runtime` / `--allow-beta` on
+  `dh admin agent elastic-create`.
+- **Monitoring.** `dh admin agent monitoring` takes `--window` or `--start`/`--end`, and
+  `dh admin agent queries` lists the runs behind a time range, sortable by wait, duration,
+  peak memory, CPU time, spill or bytes read.
+- **Maintenance.** `dh admin maintenance recommendations` and `dh admin maintenance apply`
+  (asks first; needs `maintenance:manage`).
+- **Worksheets.** `dh worksheet list|get|create|update|delete`. Changing a worksheet's
+  title or SQL requires `--base-version`; a concurrent edit is refused with exit `5` and
+  the current worksheet in the error's details.
+- `dh saved-query create --on-conflict error` fails with exit `5` instead of overwriting
+  a query with the same name, and `dh search --type` limits the kinds of object searched.
+
+### Changed
+
+- With no agent named, `dh sql` and `dh session open` no longer list agents first and leave
+  the choice to the server, which picks a connected agent on the default runtime. Before,
+  an account that could see several agents sent no choice and a server without elastic
+  compute refused with `agent_required`.
+- Status polls ask the server to hold the call until the query finishes, and a query the
+  submit response already reports as finished is not polled at all.
+- The pinned API contract is refreshed, and now also checks the query parameters the new
+  commands send.
+
+## [0.2.0] - 2026-09-09
+
+### Changed
+
+- Drop support for Python 3.10; the minimum supported version is now 3.11.
+
+## [0.1.1] - 2026-09-09
+
+### Fixed
+
+- Declare `click` as a direct dependency. `dh` failed to start with
+  `ModuleNotFoundError: No module named 'click'` when installed standalone:
+  `context.py`/`repl.py` catch `click.Abort` directly, but `typer>=0.27` no longer
+  depends on `click` itself, and the workspace dev environment masked this because
+  other packages pulled `click` in transitively.
+
+## [0.1.0] - 2026-09-09
+
+### Added
+
+- `dh`, the DuckHaven command-line interface.
+- **Running SQL.** `dh sql` submits, polls to a terminal state and fetches every page
+  of results; `--no-wait` returns the id instead. Ctrl-C cancels the query on the
+  server rather than orphaning it, and a query that runs and fails exits `6` so a
+  pipeline can tell bad SQL from a broken CLI. `dh sql` with no arguments on a
+  terminal opens a REPL, session-backed where the server allows it.
+- **The dbt path.** `dh lineage import` and `dh semantic import` publish build
+  artifacts, including the `manifest.json` + `catalog.json` pair that unlocks
+  column-level lineage, plus `validate`/`publish` to promote imported drafts.
+- **Catalog and access.** `dh workspace`, `dh catalog`, `dh schema`, `dh table` and
+  `dh grant`, with catalog resolution and `catalog.schema.table` references.
+- **History.** `dh query list` with the full server-side filter set, `dh saved-query`,
+  `dh schedule` and `dh search`.
+- **Operators.** A thin `dh admin` over service accounts, tokens, users and agents,
+  and `dh api` for anything without a hand-written command.
+- **Auth.** `dh auth login` signs in and mints a personal access token, storing only
+  the token at mode 0600 and refusing a config other users can read.
+- Output as `--format json|table|csv` behind one stable envelope
+  (`{data, cursor, has_more}`), defaulting to a table on a terminal and JSON when
+  piped. Errors are JSON too when JSON was asked for.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: duckhaven-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: dh — the command-line interface for DuckHaven
 Project-URL: Homepage, https://github.com/tamasmrtn/duckhaven-clients
 Project-URL: Source, https://github.com/tamasmrtn/duckhaven-clients
@@ -21,10 +21,10 @@ Classifier: Topic :: Database
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: click>=8.0
+Requires-Dist: click>=8.5.0
 Requires-Dist: duckhaven-sql-connector>=0.4.1
 Requires-Dist: httpx>=0.28
-Requires-Dist: typer>=0.15
+Requires-Dist: typer>=0.27.3
 Description-Content-Type: text/markdown
 
 # duckhaven-cli
@@ -57,6 +57,34 @@ dh auth login --host https://duckhaven.example.com
 dh sql -q "select 1"
 ```
 
+## The result cache
+
+DuckHaven answers a repeated read from its result cache when nothing the query reads has
+changed. `dh sql` says so on stderr when it happens; pass `--no-cache` to run the query
+anyway (also on `dh session open` and `dh session exec`). An owner can switch the cache off
+for a whole workspace with `dh workspace update --no-result-cache`. The interactive REPL
+does not take `--no-cache`: it holds its session through the connector, which has its own
+`use_cache` option, and the shell does not expose it yet.
+
+## Newer server features
+
+A server that supports them offers: DuckLake catalogs (`dh catalog kinds`,
+`dh catalog create --kind ducklake`, `dh catalog rotate-role`, `dh catalog export`), the
+DuckDB runtimes agents run (`dh agent runtimes`, `--runtime` on
+`dh admin agent elastic-create`), per-agent monitoring over a window or range and the
+queries behind it (`dh admin agent monitoring`, `dh admin agent queries`), applying
+maintenance recommendations (`dh admin maintenance recommendations|apply`), and your
+private editor tabs (`dh worksheet`). Against an older server these commands answer with the
+server's own not-found or validation error.
+
+## Exact numbers
+
+A DuckHaven with `api_version` 3 or later sends `DECIMAL` values and 64-bit-or-wider integers
+(`BIGINT`, `HUGEINT`, `count(*)`) as strings, because JSON numbers lose precision past about
+16 digits. `dh` prints them exactly as before in table and CSV output. With `--format json`
+they stay strings (`"12.50"`, `"9007199254740993"`), exact. Scripts reading `dh` JSON should
+convert those columns themselves rather than expect JSON numbers.
+
 ## Documentation
 
 - [Command-line quickstart](https://tamasmrtn.github.io/duckhaven/getting-started/cli-quickstart/) — install, sign in,

duckhaven_cli-0.4.0/README.md

@@ -0,0 +1,67 @@
+# duckhaven-cli
+
+`dh` — the command-line interface for [DuckHaven](https://github.com/tamasmrtn/duckhaven).
+
+It gives analysts, CI pipelines and operators scriptable access to DuckHaven's REST API:
+running SQL, browsing the catalog, publishing dbt lineage and semantic models, managing
+grants, and operating service accounts, users and agents.
+
+Like every member of this repo it is a **pure HTTP client of DuckHaven's public REST
+API**, authenticating with a Personal Access Token (`dh_pat_…`). The interactive REPL
+holds a SQL session through
+[`duckhaven-sql-connector`](../duckhaven-sql-connector/README.md); everything else,
+including one-shot `dh sql`, goes over the REST API directly, because the one-shot query
+route works on deployments where SQL sessions are switched off.
+
+## Install
+
+```sh
+pip install duckhaven-cli
+# or, to get an isolated tool install:
+uv tool install duckhaven-cli
+```
+
+## Getting started
+
+```sh
+dh auth login --host https://duckhaven.example.com
+dh sql -q "select 1"
+```
+
+## The result cache
+
+DuckHaven answers a repeated read from its result cache when nothing the query reads has
+changed. `dh sql` says so on stderr when it happens; pass `--no-cache` to run the query
+anyway (also on `dh session open` and `dh session exec`). An owner can switch the cache off
+for a whole workspace with `dh workspace update --no-result-cache`. The interactive REPL
+does not take `--no-cache`: it holds its session through the connector, which has its own
+`use_cache` option, and the shell does not expose it yet.
+
+## Newer server features
+
+A server that supports them offers: DuckLake catalogs (`dh catalog kinds`,
+`dh catalog create --kind ducklake`, `dh catalog rotate-role`, `dh catalog export`), the
+DuckDB runtimes agents run (`dh agent runtimes`, `--runtime` on
+`dh admin agent elastic-create`), per-agent monitoring over a window or range and the
+queries behind it (`dh admin agent monitoring`, `dh admin agent queries`), applying
+maintenance recommendations (`dh admin maintenance recommendations|apply`), and your
+private editor tabs (`dh worksheet`). Against an older server these commands answer with the
+server's own not-found or validation error.
+
+## Exact numbers
+
+A DuckHaven with `api_version` 3 or later sends `DECIMAL` values and 64-bit-or-wider integers
+(`BIGINT`, `HUGEINT`, `count(*)`) as strings, because JSON numbers lose precision past about
+16 digits. `dh` prints them exactly as before in table and CSV output. With `--format json`
+they stay strings (`"12.50"`, `"9007199254740993"`), exact. Scripts reading `dh` JSON should
+convert those columns themselves rather than expect JSON numbers.
+
+## Documentation
+
+- [Command-line quickstart](https://tamasmrtn.github.io/duckhaven/getting-started/cli-quickstart/) — install, sign in,
+  run a query
+- [CLI reference](https://tamasmrtn.github.io/duckhaven/reference/cli/) — every command and flag
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).

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

@@ -22,10 +22,10 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "typer>=0.15",
+    "typer>=0.27.3",
     # click.Abort is caught directly (Ctrl-C/Ctrl-D handling); typer>=0.27 no longer
     # pulls click in as its own dependency, so it must be declared here too.
-    "click>=8.0",
+    "click>=8.5.0",
     "httpx>=0.28",
     # The SQL execution path (sessions, statements, polling, row pagination) is the
     # connector's, not a second implementation of it.

{duckhaven_cli-0.2.0 → duckhaven_cli-0.4.0}/src/dh/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
 __commit_id__ = commit_id = None

{duckhaven_cli-0.2.0 → duckhaven_cli-0.4.0}/src/dh/commands/admin.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 import typer
 
 from dh import context
+from dh.errors import ConflictError
 
 app = typer.Typer(name="admin", help="Operator tasks: accounts, users, agents.")
 
@@ -20,9 +21,12 @@ pat_app = typer.Typer(name="pat", help="Tokens issued to a service account.")
 user_app = typer.Typer(name="user", help="People and their workspace roles.")
 agent_app = typer.Typer(name="agent", help="Compute agents.")
 storage_app = typer.Typer(name="storage", help="Storage backends.")
-maintenance_app = typer.Typer(name="maintenance", help="Deployment maintenance policy.")
+maintenance_app = typer.Typer(
+    name="maintenance", help="Maintenance policy, scans and recommendations."
+)
+catalog_app = typer.Typer(name="catalog", help="Catalog-wide operations.")
 
-for sub in (sa_app, pat_app, user_app, agent_app, storage_app, maintenance_app):
+for sub in (sa_app, pat_app, user_app, agent_app, storage_app, maintenance_app, catalog_app):
     app.add_typer(sub)
 
 
@@ -239,12 +243,24 @@ def create_elastic_agent(
     cpu: float = typer.Option(..., "--cpu"),
     memory_gb: float = typer.Option(..., "--memory-gb"),
     idle_timeout_minutes: int = typer.Option(None, "--idle-timeout-minutes"),
+    runtime: str = typer.Option(
+        None,
+        "--runtime",
+        help="DuckDB runtime id, from `dh agent runtimes`. Omitted: the deployment's default.",
+    ),
+    allow_beta: bool = typer.Option(
+        False, "--allow-beta", help="Permit a beta runtime, which is otherwise refused."
+    ),
 ):
     """Provision an elastic agent. Accepted asynchronously; poll `admin agent get`."""
     cli = context.of(ctx)
     body: dict[str, object] = {"cpu": cpu, "memory_gb": memory_gb}
     if idle_timeout_minutes is not None:
         body["idle_timeout_minutes"] = idle_timeout_minutes
+    if runtime:
+        body["runtime_id"] = runtime
+    if allow_beta:
+        body["allow_beta"] = True
     with cli.client() as client:
         cli.emit(client.post("admin/agents/elastic", json=body))
 
@@ -266,11 +282,60 @@ def agent_metrics(ctx: typer.Context):
 
 
 @agent_app.command("monitoring")
-def agent_monitoring(ctx: typer.Context, agent_id: str):
-    """One agent's monitoring detail."""
+def agent_monitoring(
+    ctx: typer.Context,
+    agent_id: str,
+    window: str = typer.Option(
+        None, "--window", help="A preset ending now: 1h, 3h, 8h (the default), 12h, 24h, 3d or 7d."
+    ),
+    start: str = typer.Option(None, "--start", help="ISO-8601 start of a custom range."),
+    end: str = typer.Option(None, "--end", help="ISO-8601 end of a custom range."),
+):
+    """One agent's monitoring detail over a window or a custom range.
+
+    Returns flat time buckets (busy, idle, concurrency, outcomes, CPU and memory)
+    on one shared grid, the lifecycle spans and a summary for the range.
+    """
     cli = context.of(ctx)
+    if (start is None) != (end is None):
+        raise ConflictError("bad_range", "Give both --start and --end, or neither.")
+    if window and start:
+        raise ConflictError("bad_range", "Give --window or --start/--end, not both.")
+    params = {"window": window, "start": start, "end": end}
     with cli.client() as client:
-        cli.emit(client.get(f"admin/agents/{agent_id}/monitoring"))
+        cli.emit(client.get(f"admin/agents/{agent_id}/monitoring", params=params))
+
+
+@agent_app.command("queries")
+def agent_queries(
+    ctx: typer.Context,
+    agent_id: str,
+    start: str = typer.Option(..., "--start", help="ISO-8601 start of the range."),
+    end: str = typer.Option(..., "--end", help="ISO-8601 end of the range."),
+    status: list[str] = typer.Option(None, "--status", help="Repeatable."),
+    sort: str = typer.Option(
+        None,
+        "--sort",
+        help="started_at (default), duration, wait, peak_memory, cpu_time, spill or bytes_read.",
+    ),
+    direction: str = typer.Option(None, "--dir", help="asc or desc (default)."),
+    limit: int = typer.Option(None, "--limit"),
+    fetch_all: bool = typer.Option(False, "--all"),
+):
+    """The runs that were running or waiting on an agent during a range, with what they cost.
+
+    Needs the permission to see queries across workspaces as well as `use` on the agent.
+    """
+    cli = context.of(ctx)
+    params = {"start": start, "end": end, "status": status, "sort": sort, "dir": direction}
+    with cli.client() as client:
+        cli.page(
+            client,
+            f"admin/agents/{agent_id}/queries",
+            params=params,
+            limit=limit,
+            fetch_all=fetch_all,
+        )
 
 
 @agent_app.command("access")
@@ -351,3 +416,51 @@ def trigger_scan(ctx: typer.Context):
     cli = context.of(ctx)
     with cli.client() as client:
         cli.emit(client.post("admin/maintenance/scan"))
+
+
+@maintenance_app.command("recommendations")
+def list_recommendations(
+    ctx: typer.Context,
+    status: list[str] = typer.Option(None, "--status", help="Repeatable."),
+    severity: list[str] = typer.Option(None, "--severity", help="Repeatable."),
+    limit: int = typer.Option(None, "--limit"),
+    fetch_all: bool = typer.Option(False, "--all"),
+):
+    """What the maintenance scan recommends, with the outcome of any apply."""
+    cli = context.of(ctx)
+    params = {"status": status, "severity": severity}
+    with cli.client() as client:
+        cli.page(
+            client, "maintenance/recommendations", params=params, limit=limit, fetch_all=fetch_all
+        )
+
+
+@maintenance_app.command("apply")
+def apply_recommendation(ctx: typer.Context, recommendation_id: str, yes: bool = context.YES):
+    """Run the maintenance a recommendation asks for.
+
+    Rewrites or deletes data files, so it asks first. Needs `maintenance:manage` and
+    only works for catalog kinds that support applying (see `dh catalog kinds`).
+    Accepted asynchronously: the recommendation's `apply_status` reports the outcome,
+    so follow with `dh admin maintenance recommendations`.
+    """
+    cli = context.of(ctx)
+    cli.confirm("Apply maintenance recommendation", recommendation_id, yes=yes)
+    with cli.client() as client:
+        cli.emit(client.post(f"maintenance/recommendations/{recommendation_id}/apply"))
+
+
+# --- Catalogs ----------------------------------------------------------------
+
+
+@catalog_app.command("reconcile-roles")
+def reconcile_ducklake_roles(ctx: typer.Context):
+    """Create any DuckLake database role that does not exist yet.
+
+    A post-upgrade step for operators: a migration can only write the credentials,
+    not the roles themselves in the catalog database. Idempotent, and it also repairs
+    a role that was dropped. Prints how many catalogs it saw and how many it reconciled.
+    """
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.emit(client.post("admin/catalogs/ducklake/reconcile-roles"))

{duckhaven_cli-0.2.0 → duckhaven_cli-0.4.0}/src/dh/commands/catalog.py

@@ -102,13 +102,21 @@ def update_workspace(
     workspace: str = typer.Argument(None),
     name: str = typer.Option(None, "--name"),
     description: str = typer.Option(None, "--description"),
+    result_cache: bool = typer.Option(
+        None,
+        "--result-cache/--no-result-cache",
+        help="Whether repeated queries may be answered from the result cache. Owner only.",
+    ),
 ) -> None:
-    """Rename or re-describe a workspace."""
+    """Rename or re-describe a workspace, or switch its result cache on or off."""
     cli = context.of(ctx)
     settings = cli.settings()
-    body = {k: v for k, v in {"name": name, "description": description}.items() if v is not None}
+    fields = {"name": name, "description": description, "result_cache_enabled": result_cache}
+    body = {k: v for k, v in fields.items() if v is not None}
     if not body:
-        raise ConflictError("nothing_to_update", "Give --name or --description.")
+        raise ConflictError(
+            "nothing_to_update", "Give --name, --description or --result-cache/--no-result-cache."
+        )
     with cli.client(settings) as client:
         target = workspace or settings.require("workspace")
         cli.emit(client.patch(f"workspaces/{target}", json=body))
@@ -171,6 +179,19 @@ def list_agents(ctx: typer.Context) -> None:
         cli.emit(client.get("agents"))
 
 
+@agent_app.command("runtimes")
+def list_runtimes(ctx: typer.Context) -> None:
+    """The DuckDB runtimes agents can run, and which one is the default.
+
+    Each is a DuckDB line with its baked-in extensions and a lifecycle status
+    (`beta`, `ga`, `deprecated`, `retired`). Retired runtimes are listed so an agent
+    still running one can be recognised, but the server will not send them work.
+    """
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.emit(client.get("runtimes"))
+
+
 # --- Catalogs --------------------------------------------------------------
 
 
@@ -191,6 +212,11 @@ def list_catalogs(
 def create_catalog(
     ctx: typer.Context,
     name: str = typer.Argument(..., help="Identifier-safe name."),
+    kind: str = typer.Option(
+        None,
+        "--kind",
+        help="iceberg_polaris (the server default) or ducklake. See `dh catalog kinds`.",
+    ),
     storage_backend: str = typer.Option(None, "--storage-backend", help="Backend id."),
     access_mode: str = typer.Option(None, "--access-mode", help="open or scoped."),
 ) -> None:
@@ -198,6 +224,8 @@ def create_catalog(
     cli = context.of(ctx)
     settings = cli.settings()
     body = {"name": name}
+    if kind:
+        body["kind"] = kind
     if storage_backend:
         body["storage_backend_id"] = storage_backend
     if access_mode:
@@ -206,6 +234,82 @@ def create_catalog(
         cli.emit(client.post(f"workspaces/{settings.require('workspace')}/catalogs", json=body))
 
 
+@catalog_app.command("kinds")
+def list_catalog_kinds(ctx: typer.Context) -> None:
+    """The catalog kinds this deployment offers, and what each can do.
+
+    A kind that is known but switched off is listed with `available: false` and the
+    reason, so `dh catalog create --kind` failing is explicable.
+    """
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.emit(client.get("catalog-kinds"))
+
+
+@catalog_app.command("rotate-role")
+def rotate_role(ctx: typer.Context, catalog_id: str, yes: bool = context.YES) -> None:
+    """Rotate the database credential of a DuckLake catalog.
+
+    Queries already running keep their connection; ones that start afterwards use
+    the new credential.
+    """
+    cli = context.of(ctx)
+    cli.confirm("Rotate the database role of catalog", catalog_id, yes=yes)
+    with cli.client() as client:
+        cli.emit(client.post(f"catalogs/{catalog_id}/ducklake/rotate-role"))
+
+
+export_app = typer.Typer(name="export", help="Copy a DuckLake catalog out as Iceberg.")
+catalog_app.add_typer(export_app)
+
+
+@export_app.command("list")
+def list_exports(
+    ctx: typer.Context, catalog_id: str, fetch_all: bool = typer.Option(False, "--all")
+) -> None:
+    """A catalog's exports, newest first."""
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.page(client, f"catalogs/{catalog_id}/exports", fetch_all=fetch_all)
+
+
+@export_app.command("create")
+def create_export(
+    ctx: typer.Context,
+    catalog_id: str,
+    target_name: str = typer.Option(..., "--target-name", help="Name of the new Iceberg catalog."),
+    storage_backend: str = typer.Option(
+        ..., "--storage-backend", help="Storage backend id for the new catalog."
+    ),
+) -> None:
+    """Start exporting a DuckLake catalog to a new Iceberg catalog.
+
+    The new catalog is attached to the current workspace. This only starts the
+    export; follow it with `dh catalog export list`.
+    """
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(
+            client.post(
+                f"catalogs/{catalog_id}/exports",
+                params={"workspace": settings.require("workspace")},
+                json={
+                    "target_name": target_name,
+                    "target_storage_backend_id": storage_backend,
+                },
+            )
+        )
+
+
+@export_app.command("cancel")
+def cancel_export(ctx: typer.Context, catalog_id: str, export_id: str) -> None:
+    """Stop an export that has not finished."""
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.emit(client.post(f"catalogs/{catalog_id}/exports/{export_id}/cancel"))
+
+
 @catalog_app.command("attach")
 def attach_catalog(
     ctx: typer.Context,

{duckhaven_cli-0.2.0 → duckhaven_cli-0.4.0}/src/dh/commands/query.py

@@ -41,6 +41,7 @@ def _run(
     limit: int | None,
     fetch_all: bool,
     agent: str | None,
+    no_cache: bool,
 ) -> None:
     cli = context.of(ctx)
     settings = cli.settings()
@@ -62,16 +63,20 @@ def _run(
             # The same budget bounds the client's wait and the server's execution.
             # Two timeouts would be a contract people get wrong; one cannot drift.
             timeout_s=budget,
+            use_cache=False if no_cache else None,
+            hold=not no_wait,
         )
         if no_wait:
             cli.note(f"Submitted {submitted['id']}.")
             cli.emit(submitted)
             return
 
-        finished = execute.wait(client, submitted["id"], timeout=budget)
+        finished = execute.wait(client, submitted["id"], timeout=budget, known=submitted)
         execute.raise_for_status(finished)
         page = execute.fetch_rows(client, finished["id"], limit=None if fetch_all else limit)
 
+    if finished.get("cache_status") == "hit":
+        cli.note("Answered from the result cache. Use --no-cache to run it again.")
     if page["truncated"]:
         cli.note(f"Showing {len(page['rows'])} of {page['total']} rows. Use --all for the rest.")
     cli.emit({"columns": page["columns"], "rows": page["rows"], "total": page["total"]})
@@ -85,6 +90,11 @@ _TIMEOUT = typer.Option("20m", "--timeout", help="Give up after this long, e.g.
 _LIMIT = typer.Option(None, "--limit", help="Stop after this many rows.")
 _ALL = typer.Option(False, "--all", help="Fetch every row, ignoring --limit.")
 _AGENT = typer.Option(None, "--agent", help="Agent name or id to run on.")
+_NO_CACHE = typer.Option(
+    False,
+    "--no-cache",
+    help="Always run the query instead of answering it from the result cache.",
+)
 
 
 def sql(
@@ -97,6 +107,7 @@ def sql(
     limit: int = _LIMIT,
     fetch_all: bool = _ALL,
     agent: str = _AGENT,
+    no_cache: bool = _NO_CACHE,
 ) -> None:
     """Run SQL and print the results.
 
@@ -117,6 +128,7 @@ def sql(
         limit=limit,
         fetch_all=fetch_all,
         agent=agent,
+        no_cache=no_cache,
     )
 
 
@@ -131,6 +143,7 @@ def run_query(
     limit: int = _LIMIT,
     fetch_all: bool = _ALL,
     agent: str = _AGENT,
+    no_cache: bool = _NO_CACHE,
 ) -> None:
     """Run SQL and print the results. The noun-first spelling of `dh sql`."""
     _run(
@@ -143,6 +156,7 @@ def run_query(
         limit=limit,
         fetch_all=fetch_all,
         agent=agent,
+        no_cache=no_cache,
     )