duckhaven-cli 0.1.0__py3-none-any.whl

dh/commands/auth.py

@@ -0,0 +1,266 @@
+"""`dh auth` — signing in, and inspecting the credential in use."""
+
+from __future__ import annotations
+
+import math
+
+# `datetime.UTC` is 3.11+, and this package supports 3.10. Importing it here
+# broke every test that loads the app, on the one interpreter leg that checks.
+from datetime import datetime, timedelta, timezone
+
+import typer
+
+from dh import config as config_mod
+from dh import context
+from dh.config import Profile
+from dh.errors import AuthError, ConfigError, DhError, NotFoundError
+from dh.resolve import describe as describe_settings
+from dh.rest import RestClient
+
+app = typer.Typer(name="auth", help="Sign in, and inspect the credential in use.")
+
+
+@app.command("describe")
+def describe(ctx: typer.Context) -> None:
+    """Show which credential is in use and where each setting came from.
+
+    The question every support thread opens with. A precedence chain is hard to
+    reason about by inspection, so the CLI answers it directly rather than leaving
+    the reader to guess whether a flag, a variable or a file won.
+
+    The token is shown as a masked prefix -- enough to tell two apart, never enough
+    to use one. Makes no network call.
+    """
+    cli = context.of(ctx)
+    cfg = config_mod.load()
+    # The file path is part of the answer, not a diagnostic about it: "which
+    # config am I even reading" is half of what the command is asked.
+    rows = [{"setting": "config", "value": str(cfg.path), "source": "-"}]
+    rows.extend(describe_settings(cli.settings()))
+    cli.emit(rows)
+
+
+@app.command("login")
+def login(
+    ctx: typer.Context,
+    host: str = typer.Option(None, "--host", help="DuckHaven base URL.", metavar="URL"),
+    profile_name: str = typer.Option("default", "--name", help="Profile to write."),
+    email: str = typer.Option(None, "--email", help="Skip the email prompt."),
+    token: str = typer.Option(
+        None,
+        "--token",
+        help="Store a PAT you were given instead of signing in for one.",
+    ),
+    workspace: str = typer.Option(None, "--workspace", help="Default workspace for the profile."),
+    expires_in_days: int = typer.Option(90, "--expires-in-days", min=1, max=365),
+) -> None:
+    """Sign in and store a personal access token.
+
+    Signing in mints the token through `POST /api/me/pats` and stores only that:
+    the session cookie lives for three requests and never reaches disk. Token
+    *creation* is deliberately cookie-only on the server, because a PAT that could
+    mint PATs would outlive its own revocation.
+
+    An OIDC-only deployment has no password to collect, so pass `--token` with a
+    PAT an administrator issued. Unattended callers should not use this command at
+    all -- CI authenticates with a service-account token.
+    """
+    cli = context.of(ctx)
+    settings = cli.settings()
+    base = host or settings.get("host") or typer.prompt("DuckHaven host")
+
+    if token:
+        secret, expires_at = token, None
+    else:
+        secret, expires_at = _mint_token(base, email, expires_in_days)
+
+    # Verify before writing: a profile holding a token that does not work is worse
+    # than no profile, because the next failure looks like a server problem.
+    with RestClient(base, secret) as client:
+        try:
+            me = client.get("me")
+        except DhError as exc:
+            raise AuthError("login_failed", f"The token was not accepted: {exc.message}") from exc
+
+    cfg = config_mod.load()
+    cfg = config_mod.upsert(
+        cfg,
+        Profile(
+            name=profile_name,
+            host=base,
+            token=secret,
+            workspace=workspace or settings.get("workspace"),
+        ),
+    )
+    config_mod.save(cfg)
+    cli.note(
+        f"Logged in as {me.get('email', 'unknown')}; wrote profile {profile_name!r} to {cfg.path}."
+        + (f" Token expires {expires_at}." if expires_at else "")
+    )
+    cli.emit(
+        {"profile": profile_name, "host": base, "user": me.get("email"), "expires_at": expires_at}
+    )
+
+
+def _mint_token(base: str, email: str | None, expires_in_days: int) -> tuple[str, str | None]:
+    """Sign in with a password and exchange the session for a PAT.
+
+    One client for the whole exchange, because httpx keeps the session cookie on
+    the client and it must never be written anywhere else.
+    """
+    with RestClient(base) as client:
+        methods = client.get("auth/methods")
+        if not (methods.get("local") or methods.get("ldap")):
+            providers = ", ".join(p.get("id", "?") for p in methods.get("oidc_providers") or [])
+            raise AuthError(
+                "password_login_unavailable",
+                f"This deployment authenticates through {providers or 'an identity provider'} "
+                "only, so there is no password to sign in with. Ask an administrator for a "
+                "token and run `dh auth login --token dh_pat_...`.",
+            )
+        address = email or typer.prompt("Email")
+        password = typer.prompt("Password", hide_input=True)
+        client.post("auth/login", json={"email": address, "password": password})
+        try:
+            issued = client.post("me/pats", json={"expires_in_days": expires_in_days})
+        except NotFoundError as exc:
+            # A server predating POST /api/me/pats. Say what to do rather than
+            # reporting a bare 404 the reader cannot act on.
+            raise AuthError(
+                "self_service_unsupported",
+                "This DuckHaven is too old to issue your own token. Ask an administrator "
+                "for a service-account token and run `dh auth login --token dh_pat_...`.",
+            ) from exc
+        finally:
+            # Best effort: the token is already minted, and leaving a session open
+            # is worse than a noisy logout.
+            try:
+                client.post("auth/logout")
+            except DhError:
+                pass
+    return issued["token"], issued.get("expires_at")
+
+
+#: Warn this far ahead of expiry. A fortnight is long enough to rotate before a
+#: scheduled job breaks, and short enough that the warning still means something.
+_EXPIRY_WARNING = timedelta(days=14)
+
+
+@app.command("status")
+def status(ctx: typer.Context) -> None:
+    """Who the stored credential authenticates as, and how long it has left."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        me = client.get("me")
+        version = _optional(client, "version")
+        current = _current_token(client)
+    expires_at = (current or {}).get("expires_at")
+    _warn_if_expiring(cli, expires_at)
+    cli.emit(
+        {
+            "host": settings.get("host"),
+            "profile": settings.get("profile"),
+            "user": me.get("email"),
+            "name": me.get("name"),
+            "role": me.get("role"),
+            "workspace": settings.get("workspace"),
+            "token_expires_at": expires_at,
+            "server_version": (version or {}).get("version"),
+            "api_version": (version or {}).get("api_version"),
+        }
+    )
+
+
+def _current_token(client: RestClient) -> dict | None:
+    """The token this request is authenticating with, if the server can say.
+
+    Only a hash is stored, so the server marks the caller's own row rather than
+    returning anything identifiable. A server predating the route reports
+    nothing, which is a missing warning rather than a failure.
+    """
+    try:
+        rows = client.get("me/pats") or []
+    except DhError:
+        return None
+    return next((row for row in rows if row.get("current")), None)
+
+
+def _warn_if_expiring(cli, expires_at: str | None) -> None:
+    """Say something before a token expires, not after.
+
+    The first symptom of an expired token is a 401 in a job nobody was watching,
+    which is the failure this whole listing exists to prevent.
+    """
+    if not expires_at:
+        return
+    try:
+        moment = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
+    except ValueError:  # pragma: no cover - the server sends ISO-8601
+        return
+    left = moment - datetime.now(tz=moment.tzinfo or timezone.utc)
+    if left <= timedelta(0):
+        cli.note("This token has expired. Run `dh auth login` to get a new one.")
+    elif left <= _EXPIRY_WARNING:
+        # Rounded up, not truncated: `timedelta.days` on 71h59m is 2, so a token
+        # with three days left would be reported as two -- and one with hours left
+        # as zero, which reads like it is already dead.
+        days = math.ceil(left.total_seconds() / 86400)
+        cli.note(
+            f"This token expires in {days} day{'s' if days != 1 else ''}. "
+            "Run `dh auth login` to replace it."
+        )
+
+
+@app.command("tokens")
+def list_tokens(ctx: typer.Context) -> None:
+    """Your own tokens: when each was issued, when it expires, which is in use.
+
+    Never the secret. A token is shown once, when it is issued; only its hash is
+    kept, so a forgotten one is replaced rather than recovered.
+    """
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.emit(client.get("me/pats"))
+
+
+@app.command("revoke")
+def revoke_token(ctx: typer.Context, pat_id: str) -> None:
+    """Revoke one of your own tokens, by the id `dh auth tokens` shows.
+
+    Revoking the token you are currently using works and takes effect at once,
+    which is the right move if you think it has leaked.
+    """
+    cli = context.of(ctx)
+    with cli.client() as client:
+        client.delete(f"me/pats/{pat_id}")
+    cli.note(f"Revoked token {pat_id}.")
+
+
+@app.command("logout")
+def logout(ctx: typer.Context, profile_name: str = typer.Option(None, "--name")) -> None:
+    """Forget the stored token, keeping the rest of the profile.
+
+    Local only: the token stays valid server-side until it expires. To retire
+    it as well, run `dh auth revoke <id>` first -- `dh auth tokens` shows the id.
+    """
+    cli = context.of(ctx)
+    cfg = config_mod.load()
+    target = profile_name or cfg.resolved_default()
+    profile = cfg.get(target) if target else None
+    if profile is None:
+        raise ConfigError("no_such_profile", f"No profile named {target!r} in {cfg.path}")
+    config_mod.save(config_mod.upsert(cfg, Profile(**{**vars(profile), "token": None})))
+    cli.note(f"Cleared the token for profile {target!r}. It remains valid until it expires.")
+
+
+def _optional(client: RestClient, path: str) -> dict | None:
+    """A GET whose absence is a supported answer.
+
+    `GET /api/version` postdates the oldest servers `dh` supports, and the
+    connector treats its 404 the same way.
+    """
+    try:
+        return client.get(path)
+    except NotFoundError:
+        return None

dh/commands/catalog.py

@@ -0,0 +1,426 @@
+"""`dh workspace`, `dh catalog`, `dh schema` and `dh table`.
+
+Every schema and table route names its catalog explicitly -- the workspace-default
+shim was removed from the API -- so a catalog has to be resolved before any of
+these can build a URL. That resolution is the one piece of shared state here, and
+getting it wrong reads the wrong catalog silently, so it is done in one place and
+echoed under `--debug`.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from dh import context
+from dh.errors import ConflictError
+from dh.rest import RestClient
+
+workspace_app = typer.Typer(name="workspace", help="Workspaces and their members.")
+catalog_app = typer.Typer(name="catalog", help="Catalogs attached to a workspace.")
+schema_app = typer.Typer(name="schema", help="Schemas within a catalog.")
+table_app = typer.Typer(name="table", help="Tables, their metadata and a sample of rows.")
+
+
+def resolve_catalog(cli, client: RestClient, settings, override: str | None = None) -> str:
+    """The catalog to address, and where it came from.
+
+    Order: an explicit value, then the resolved settings, then the workspace's own
+    default. The last lookup costs a request, which is why it is only reached when
+    nothing nearer answered.
+    """
+    if override:
+        return override
+    from_settings = settings.get("catalog")
+    if from_settings:
+        cli.debug(f"catalog {from_settings} ({settings.source('catalog')})")
+        return from_settings
+    workspace = client.get(f"workspaces/{settings.require('workspace')}")
+    default = workspace.get("default_catalog")
+    if not default:
+        raise ConflictError(
+            "no_catalog",
+            "No catalog given and the workspace has no default. "
+            "Set one with --catalog, $DH_CATALOG, or in your profile.",
+        )
+    cli.debug(f"catalog {default} (workspace default)")
+    return default
+
+
+def split_ref(ref: str, *, want: int) -> list[str]:
+    """Split `schema.table` or `catalog.schema.table` into its parts.
+
+    The three-part form overrides the resolved catalog, which is how a one-off
+    cross-catalog read stays a single command rather than a flag dance.
+    """
+    parts = ref.split(".")
+    if len(parts) == want:
+        return [None, *parts]  # type: ignore[list-item]
+    if len(parts) == want + 1:
+        return parts
+    shape = "catalog.schema.table" if want == 2 else "catalog.schema"
+    raise ConflictError(
+        "bad_reference",
+        f"Could not read {ref!r}. Use {'.'.join(['schema', 'table'][:want])} or {shape}.",
+    )
+
+
+# --- Workspaces ------------------------------------------------------------
+
+
+@workspace_app.command("list")
+def list_workspaces(ctx: typer.Context) -> None:
+    """Workspaces you can see."""
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.emit(client.get("workspaces"))
+
+
+@workspace_app.command("get")
+def get_workspace(ctx: typer.Context, workspace: str = typer.Argument(None)) -> None:
+    """One workspace, by slug or id. Defaults to the configured one."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(client.get(f"workspaces/{workspace or settings.require('workspace')}"))
+
+
+@workspace_app.command("create")
+def create_workspace(
+    ctx: typer.Context,
+    slug: str = typer.Argument(..., help="URL-safe identifier."),
+    name: str = typer.Option(None, "--name", help="Display name. Defaults to the slug."),
+) -> None:
+    """Create a workspace."""
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.emit(client.post("workspaces", json={"slug": slug, "name": name or slug}))
+
+
+@workspace_app.command("update")
+def update_workspace(
+    ctx: typer.Context,
+    workspace: str = typer.Argument(None),
+    name: str = typer.Option(None, "--name"),
+    description: str = typer.Option(None, "--description"),
+) -> None:
+    """Rename or re-describe a workspace."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    body = {k: v for k, v in {"name": name, "description": description}.items() if v is not None}
+    if not body:
+        raise ConflictError("nothing_to_update", "Give --name or --description.")
+    with cli.client(settings) as client:
+        target = workspace or settings.require("workspace")
+        cli.emit(client.patch(f"workspaces/{target}", json=body))
+
+
+@workspace_app.command("delete")
+def delete_workspace(ctx: typer.Context, workspace: str, yes: bool = context.YES) -> None:
+    """Delete a workspace."""
+    cli = context.of(ctx)
+    cli.confirm("Delete workspace", workspace, yes=yes)
+    with cli.client() as client:
+        client.delete(f"workspaces/{workspace}")
+    cli.note(f"Deleted workspace {workspace!r}.")
+
+
+member_app = typer.Typer(name="member", help="Workspace membership.")
+workspace_app.add_typer(member_app)
+
+
+@member_app.command("list")
+def list_members(ctx: typer.Context) -> None:
+    """Who belongs to the workspace, and in what role."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(client.get(f"workspaces/{settings.require('workspace')}/members"))
+
+
+@member_app.command("add")
+def add_member(
+    ctx: typer.Context,
+    user_id: str = typer.Argument(..., help="User id to add."),
+    role: str = typer.Option("reader", "--role", help="reader, writer or owner."),
+) -> None:
+    """Add a member to the workspace."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(
+            client.post(
+                f"workspaces/{settings.require('workspace')}/members",
+                json={"user_id": user_id, "role": role},
+            )
+        )
+
+
+agent_app = typer.Typer(name="agent", help="Compute agents you may run queries on.")
+
+
+@agent_app.command("list")
+def list_agents(ctx: typer.Context) -> None:
+    """The agents this caller may run queries on, with their capabilities.
+
+    Distinct from `dh admin agent list`, which needs `agents:manage` and shows
+    every agent in the deployment. This is the list an analyst can actually use,
+    and it is where `--agent <name>` resolves a name from.
+    """
+    cli = context.of(ctx)
+    with cli.client() as client:
+        cli.emit(client.get("agents"))
+
+
+# --- Catalogs --------------------------------------------------------------
+
+
+@catalog_app.command("list")
+def list_catalogs(
+    ctx: typer.Context,
+    everywhere: bool = typer.Option(False, "--all", help="Every catalog, not just attached ones."),
+) -> None:
+    """Catalogs attached to the workspace."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        path = "catalogs" if everywhere else f"workspaces/{settings.require('workspace')}/catalogs"
+        cli.emit(client.get(path))
+
+
+@catalog_app.command("create")
+def create_catalog(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Identifier-safe name."),
+    storage_backend: str = typer.Option(None, "--storage-backend", help="Backend id."),
+    access_mode: str = typer.Option(None, "--access-mode", help="open or scoped."),
+) -> None:
+    """Create a catalog and attach it to the workspace."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    body = {"name": name}
+    if storage_backend:
+        body["storage_backend_id"] = storage_backend
+    if access_mode:
+        body["access_mode"] = access_mode
+    with cli.client(settings) as client:
+        cli.emit(client.post(f"workspaces/{settings.require('workspace')}/catalogs", json=body))
+
+
+@catalog_app.command("attach")
+def attach_catalog(
+    ctx: typer.Context,
+    catalog: str,
+    make_default: bool = typer.Option(
+        False, "--default", help="Also make it the workspace's default catalog."
+    ),
+) -> None:
+    """Attach an existing catalog to the workspace."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    body = {"make_default": True} if make_default else None
+    with cli.client(settings) as client:
+        cli.emit(
+            client.put(f"workspaces/{settings.require('workspace')}/catalogs/{catalog}", json=body)
+        )
+
+
+@catalog_app.command("detach")
+def detach_catalog(ctx: typer.Context, catalog: str, yes: bool = context.YES) -> None:
+    """Detach a catalog from the workspace. The catalog itself survives."""
+    cli = context.of(ctx)
+    cli.confirm("Detach catalog", catalog, yes=yes)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        client.delete(f"workspaces/{settings.require('workspace')}/catalogs/{catalog}")
+    cli.note(f"Detached {catalog!r}.")
+
+
+@catalog_app.command("drop")
+def drop_catalog(ctx: typer.Context, catalog_id: str, yes: bool = context.YES) -> None:
+    """Drop a catalog outright, by id. Destructive."""
+    cli = context.of(ctx)
+    cli.confirm("Drop catalog", catalog_id, yes=yes)
+    with cli.client() as client:
+        client.delete(f"catalogs/{catalog_id}")
+    cli.note(f"Dropped catalog {catalog_id}.")
+
+
+@catalog_app.command("refresh-stats")
+def refresh_stats(ctx: typer.Context, catalog: str = typer.Option(None, "--catalog")) -> None:
+    """Recompute table statistics across the catalog."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        target = resolve_catalog(cli, client, settings, catalog)
+        cli.emit(
+            client.post(
+                f"workspaces/{settings.require('workspace')}/catalogs/{target}/refresh-stats"
+            )
+        )
+
+
+# --- Schemas ---------------------------------------------------------------
+
+
+def _schema_base(cli, client, settings, catalog: str | None) -> str:
+    target = resolve_catalog(cli, client, settings, catalog)
+    return f"workspaces/{settings.require('workspace')}/catalogs/{target}/schemas"
+
+
+@schema_app.command("list")
+def list_schemas(ctx: typer.Context, catalog: str = typer.Option(None, "--catalog")) -> None:
+    """Schemas in the catalog."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(client.get(_schema_base(cli, client, settings, catalog)))
+
+
+@schema_app.command("create")
+def create_schema(
+    ctx: typer.Context, name: str, catalog: str = typer.Option(None, "--catalog")
+) -> None:
+    """Create a schema."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        base = _schema_base(cli, client, settings, catalog)
+        cli.emit(client.post(base, json={"name": name}))
+
+
+@schema_app.command("drop")
+def drop_schema(
+    ctx: typer.Context,
+    name: str,
+    catalog: str = typer.Option(None, "--catalog"),
+    yes: bool = context.YES,
+) -> None:
+    """Drop a schema."""
+    cli = context.of(ctx)
+    cli.confirm("Drop schema", name, yes=yes)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        client.delete(f"{_schema_base(cli, client, settings, catalog)}/{name}")
+    cli.note(f"Dropped schema {name!r}.")
+
+
+# --- Tables ----------------------------------------------------------------
+
+
+def _table_base(cli, client, settings, ref: str, catalog: str | None, *, want: int = 2) -> str:
+    """The URL prefix for a `schema.table` (or `schema`) reference."""
+    parts = split_ref(ref, want=want)
+    explicit, rest = parts[0], parts[1:]
+    target = resolve_catalog(cli, client, settings, explicit or catalog)
+    base = f"workspaces/{settings.require('workspace')}/catalogs/{target}/schemas/{rest[0]}/tables"
+    return f"{base}/{rest[1]}" if want == 2 else base
+
+
+@table_app.command("list")
+def list_tables(
+    ctx: typer.Context,
+    schema: str = typer.Argument(..., help="schema, or catalog.schema."),
+    catalog: str = typer.Option(None, "--catalog"),
+) -> None:
+    """Tables in a schema."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(client.get(_table_base(cli, client, settings, schema, catalog, want=1)))
+
+
+@table_app.command("get")
+def get_table(
+    ctx: typer.Context,
+    table: str = typer.Argument(..., help="schema.table, or catalog.schema.table."),
+    catalog: str = typer.Option(None, "--catalog"),
+) -> None:
+    """One table's columns, partitioning and statistics."""
+    cli = context.of(ctx)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        cli.emit(client.get(_table_base(cli, client, settings, table, catalog)))
+
+
+@table_app.command("create")
+def create_table(
+    ctx: typer.Context,
+    table: str = typer.Argument(..., help="schema.table, or catalog.schema.table."),
+    column: list[str] = typer.Option(
+        ..., "--column", "-c", help="Repeatable: name:type[:null|notnull]."
+    ),
+    catalog: str = typer.Option(None, "--catalog"),
+) -> None:
+    """Create an Iceberg table.
+
+    Columns are given as `name:type`, optionally with `:notnull`. Anything more
+    elaborate is a `CREATE TABLE` through `dh sql`, which is where DDL belongs.
+    """
+    cli = context.of(ctx)
+    settings = cli.settings()
+    columns = [_column(spec) for spec in column]
+    # A table reference, but the POST goes to the *collection*: split it as a table
+    # so `sales.orders` is schema+table, then drop the last segment. Splitting it as
+    # a schema reference would read `sales` as the catalog.
+    explicit, schema, name = split_ref(table, want=2)
+    with cli.client(settings) as client:
+        target = resolve_catalog(cli, client, settings, explicit or catalog)
+        base = (
+            f"workspaces/{settings.require('workspace')}/catalogs/{target}/schemas/{schema}/tables"
+        )
+        cli.emit(client.post(base, json={"name": name, "columns": columns}))
+
+
+def _column(spec: str) -> dict[str, object]:
+    parts = spec.split(":")
+    if len(parts) not in (2, 3):
+        raise ConflictError(
+            "bad_column", f"Could not read column {spec!r}. Use name:type or name:type:notnull."
+        )
+    nullable = True
+    if len(parts) == 3:
+        if parts[2] not in ("null", "notnull"):
+            raise ConflictError("bad_column", f"Expected null or notnull, got {parts[2]!r}.")
+        nullable = parts[2] == "null"
+    return {"name": parts[0], "type": parts[1], "nullable": nullable}
+
+
+@table_app.command("drop")
+def drop_table(
+    ctx: typer.Context,
+    table: str,
+    catalog: str = typer.Option(None, "--catalog"),
+    yes: bool = context.YES,
+) -> None:
+    """Drop a table."""
+    cli = context.of(ctx)
+    cli.confirm("Drop table", table, yes=yes)
+    settings = cli.settings()
+    with cli.client(settings) as client:
+        client.delete(_table_base(cli, client, settings, table, catalog))
+    cli.note(f"Dropped {table}.")
+
+
+def _table_sub(name: str, help_text: str, *, method: str = "get"):
+    """Register the read-only sub-resources, which differ only in their suffix."""
+
+    def command(
+        ctx: typer.Context, table: str, catalog: str = typer.Option(None, "--catalog")
+    ) -> None:
+        cli = context.of(ctx)
+        settings = cli.settings()
+        with cli.client(settings) as client:
+            url = f"{_table_base(cli, client, settings, table, catalog)}/{name}"
+            cli.emit(client.get(url) if method == "get" else client.post(url))
+
+    command.__doc__ = help_text
+    return command
+
+
+table_app.command("sample")(_table_sub("sample", "A page of rows, for previewing without SQL."))
+table_app.command("snapshots")(_table_sub("snapshots", "The table's Iceberg snapshots."))
+table_app.command("lineage")(_table_sub("lineage", "What this table was built from."))
+table_app.command("health")(_table_sub("health", "Maintenance findings for this table."))
+table_app.command("recount")(
+    _table_sub("recount", "Recount the table's rows and refresh its stats.", method="post")
+)