qod-cli 0.3.7__tar.gz

qod_cli-0.3.7/.gitignore

@@ -0,0 +1,125 @@
+target/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+
+### IntelliJ IDEA ###
+.idea/modules.xml
+.idea/jarRepositories.xml
+.idea/compiler.xml
+.idea/libraries/
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+/bin/
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store
+
+### Scala ###
+.bsp/
+
+# UI build output
+src/main/resources/ui/
+ui/node_modules/
+ui/dist/
+
+# Local state file
+/state/
+
+# Runtime logs from run-jar.sh
+/logs/
+
+# Bootstrapped sbt (run-jar.sh downloads here when sbt is not on PATH)
+/.sbt-bootstrap/
+
+# IDE / OS
+.bsp/
+.metals/
+.vscode/
+.DS_Store
+
+# TypeScript build byproducts
+ui/*.tsbuildinfo
+ui/vite.config.d.ts
+ui/vite.config.js
+
+.claude/
+distrib/
+ducklake/
+certs/
+
+# DuckDB CLI + libduckdb self-installed by scripts/run-jar.sh, plus the
+# spill scratch dirs the load-{tpch,tpcds}-dbgen.sh scripts anchor for
+# SF>=10 dsdgen / dbgen runs. Both regenerate on demand from the network.
+.duckdb/
+.tmp/
+
+datasets/
+project/.bloop/
+project/project/
+
+# Local docker-compose overrides - may hold real PG_PASSWORD/ADMIN_PASSWORD/API_KEY.
+# .env.example is the tracked template.
+.env
+.env.local
+pgdata/
+seaweedfs/
+seaweedfs-config/
+
+# Native quackwire JNI shim - local CMake build tree.
+# Per-platform `libquackwire.{so,dylib}` binaries are published to Maven
+# Central as classifier jars (`ai.starlake:libquackwire:<v>:<platform>`)
+# by `.github/workflows/quackwire.yml`. The manager declares them as
+# library dependencies, so the source tree never carries them.
+native/quackwire/build*/
+
+# CI-populated binaries staging dir for `sbt libquackwire/publishSigned`.
+# Each per-platform classifier jar is built by zipping
+# libquackwire/binaries/<platform>/libquackwire.<so|dylib>.
+libquackwire/binaries/
+
+# Defense in depth: src/main/resources/native/ is no longer how
+# libquackwire reaches the assembly (the classifier deps in
+# libraryDependencies handle that). Any binaries that land here would
+# be stale relative to the published Maven coord; ignore them.
+src/main/resources/native/
+
+# Docs site (Docusaurus). The build, dependency, and generated-reference
+# outputs are produced by `sbt genConfigDocs genOpenApi` + `npm run build`
+# in CI, so they are never committed (kept in sync with the code, not the tree).
+website/node_modules/
+website/build/
+website/.docusaurus/
+website/static/openapi.yaml
+website/docs/reference/configuration.md
+src/main/scala/ai/starlake/quack/edge/.metals-scala-cli
+screens
+.venv-release/

qod_cli-0.3.7/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: qod-cli
+Version: 0.3.7
+Summary: Command-line client for quack-on-demand: admin REST plane and FlightSQL plane
+Requires-Python: >=3.10
+Requires-Dist: adbc-driver-flightsql>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pyarrow>=16.0
+Requires-Dist: pyreadline3>=3.4; sys_platform == 'win32'
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'

qod_cli-0.3.7/README.md

@@ -0,0 +1,297 @@
+# qod - the quack-on-demand CLI
+
+`qod` is a Python command-line client for quack-on-demand. It wraps the
+manager's admin REST surface (tenants, databases, pools, nodes, RBAC, catalog
+browsing, federation, audit, usage) and the FlightSQL query plane (`qod sql`,
+one-shot or interactive REPL) behind one noun-verb command tree.
+
+## Install
+
+From the repo root, against a local checkout:
+
+```bash
+pip install ./cli
+```
+
+For development (editable install, plus pytest/respx):
+
+```bash
+pip install -e 'cli[dev]'
+```
+
+Released versions are published to PyPI as `qod-cli`:
+
+```bash
+pip install qod-cli
+```
+
+Both routes install the `qod` console script.
+
+## Quick start
+
+```bash
+qod login --url http://localhost:20900 --username admin
+qod tenant list
+qod sql "SELECT 1" --tenant acme --pool bi
+```
+
+`qod login` prompts for the password (it is never a command-line flag, so it
+never lands in shell history), mints a session, and stores the session token
+plus the edge host/port/TLS settings in the active profile - one login
+configures both the REST plane and the SQL plane.
+
+## Configuration
+
+Settings resolve in this order for every field, highest priority first:
+
+1. Command-line flag (e.g. `--tenant`, `--url`)
+2. `QOD_*` environment variable
+3. Value saved in the active profile
+4. Built-in default
+
+Profiles are named sections in a TOML file at the platform config
+directory: `~/.config/qod/config.toml` on Linux, `~/Library/Application
+Support/qod/config.toml` on macOS, `%APPDATA%\qod\config.toml` on Windows.
+`QOD_CONFIG_FILE` overrides the full path. The file is written with mode
+0600 because it can hold a session token and an opt-in SQL password. Select
+a profile with `--profile NAME` or `QOD_PROFILE`; the default profile is
+named `default`.
+
+| Setting | Env var | Default | Notes |
+|---|---|---|---|
+| `manager_url` | `QOD_MANAGER_URL` | `http://localhost:20900` | REST plane base URL. |
+| `api_key` | `QOD_API_KEY` | `""` | Static API key; wins over `token` when both are set. |
+| `token` | `QOD_TOKEN` | `""` | Session JWT, normally written by `qod login`, not set by hand. |
+| `edge_host` | `QOD_HOST` | `localhost` | FlightSQL edge host. |
+| `edge_port` | `QOD_PORT` | `31338` | FlightSQL edge port. |
+| `edge_tls` | `QOD_TLS` | `true` | TLS to the edge. |
+| `edge_tls_verify` | `QOD_TLS_VERIFY` | `false` | Verify the edge TLS cert; off by default since the edge ships a self-signed cert. |
+| `tenant` | `QOD_TENANT` | `""` | Default tenant for `qod sql`. |
+| `pool` | `QOD_POOL` | `""` | Default pool for `qod sql`. |
+| `sql_user` | `QOD_USER` | `""` | FlightSQL username; set by `qod login`. |
+| `sql_password` | `QOD_PASSWORD` | `""` | FlightSQL password; opt-in storage, see "SQL plane" below. |
+| `superuser` | `QOD_SUPERUSER` | `false` | Send the superuser call header on `qod sql`. |
+
+## Command reference
+
+Output columns below are one-line purposes; run `qod <noun> <verb> --help`
+for the full flag list of any command.
+
+### Top level
+
+| Command | Purpose |
+|---|---|
+| `qod login` | Mint a session, store it and the edge settings in the active profile. |
+| `qod logout` | Revoke the current session token. |
+| `qod whoami` | Verify the current session. |
+| `qod health` | Liveness plus pool/node counts (open endpoint). |
+| `qod usage` | Usage accounting rollups. |
+| `qod sql` | Run SQL against the FlightSQL edge; one-shot or interactive REPL. |
+
+### auth - authentication mode discovery
+
+| Verb | Purpose |
+|---|---|
+| `mode` | Show the auth mode (db or oidc) the manager expects. |
+
+### config - server-published configuration
+
+| Verb | Purpose |
+|---|---|
+| `client` | Edge host/port/TLS for client bootstrapping (open endpoint). |
+| `server` | Effective manager configuration. |
+
+### tenant - tenant CRUD
+
+| Verb | Purpose |
+|---|---|
+| `list` | List tenants. |
+| `create` | Create a tenant. |
+| `delete` | Delete a tenant (must have no pools). |
+| `set-disabled` | Enable or disable a tenant. |
+| `set-auth` | Change a tenant's auth provider/config. |
+
+### database - tenant databases (DuckLake catalogs)
+
+| Verb | Purpose |
+|---|---|
+| `list` | List databases for a tenant. |
+| `create` | Create a tenant database. |
+| `update` | Update a tenant database's metastore/object-store/init settings. |
+| `delete` | Delete a tenant database. |
+
+### pool - pool lifecycle and pool-level access grants
+
+| Verb | Purpose |
+|---|---|
+| `list` | List pools. |
+| `create` | Create a pool. |
+| `scale` | Change a pool's target size and role distribution. |
+| `stop` | Stop a pool's nodes. |
+| `delete` | Delete a pool. |
+| `set-disabled` | Enable or disable a pool. |
+| `set-resources` | Set CPU/memory requests for a pool's nodes. |
+| `set-pod-template` | Set the Kubernetes pod template YAML for a pool. |
+| `permission list` | List pool access grants. |
+| `permission grant` | Grant pool access to a user or group. |
+| `permission revoke` | Revoke a pool access grant. |
+
+### node - node lifecycle and statement inspection
+
+| Verb | Purpose |
+|---|---|
+| `quarantine` | Take a node out of routing rotation. |
+| `unquarantine` | Return a node to routing rotation. |
+| `restart` | Restart a node. |
+| `set-max-concurrent` | Set a node's max concurrent statement limit. |
+| `statements` | Recent statement history, newest first. |
+| `active-statements` | Currently running statements. |
+
+### statement - statement control
+
+| Verb | Purpose |
+|---|---|
+| `kill` | Kill a running statement by id. |
+
+### user - user principals
+
+| Verb | Purpose |
+|---|---|
+| `list` | List users. |
+| `create` | Create a user (tenant-scoped, or `--superuser` for tenant-less). |
+| `update` | Update a user's tenant, password, or role. |
+| `delete` | Delete a user. |
+| `effective` | Closure of roles, groups, table permissions, and pool grants. |
+
+### role - roles, table permissions, and row/column policies
+
+| Verb | Purpose |
+|---|---|
+| `list` | List roles for a tenant. |
+| `create` | Create a role. |
+| `delete` | Delete a role. |
+| `permission list` | List table permissions attached to a role. |
+| `permission grant` | Grant a table permission to a role. |
+| `permission revoke` | Revoke a table permission from a role. |
+| `row-policy list` | List row-level security predicates on a role. |
+| `row-policy create` | Add a row-level security predicate. |
+| `row-policy update` | Update a row-level security predicate. |
+| `row-policy delete` | Delete a row-level security predicate. |
+| `column-policy list` | List column-level security policies on a role. |
+| `column-policy create` | Add a column-level security policy. |
+| `column-policy update` | Update a column-level security policy. |
+| `column-policy delete` | Delete a column-level security policy. |
+
+### group - groups
+
+| Verb | Purpose |
+|---|---|
+| `list` | List groups for a tenant. |
+| `create` | Create a group. |
+| `delete` | Delete a group. |
+
+### membership - RBAC membership edges
+
+| Verb | Purpose |
+|---|---|
+| `user-role add` | Add a user to a role. |
+| `user-role remove` | Remove a user from a role. |
+| `user-group add` | Add a user to a group. |
+| `user-group remove` | Remove a user from a group. |
+| `group-role add` | Add a role to a group. |
+| `group-role remove` | Remove a role from a group. |
+| `group-role list` | List roles held by a group. |
+
+### catalog - DuckLake catalog browsing, time travel, and recovery
+
+| Verb | Purpose |
+|---|---|
+| `schemas` | List schemas in a tenant database. |
+| `tables` | List tables in a schema. |
+| `describe` | Describe a table's columns, optionally as of a snapshot/tag/timestamp. |
+| `snapshots` | List snapshots for a tenant database, optionally filtered to a table. |
+| `history` | Snapshot history for a table (operation, author, time range filters). |
+| `preview` | Preview table rows, optionally as of a snapshot/tag/timestamp. |
+| `data-diff` | Row-level diff of a table between two snapshot selectors. |
+| `schema-diff` | Schema diff of a table between two snapshot selectors. |
+| `recoverable` | Dropped tables still recoverable via undrop. |
+| `undrop` | Recover a dropped table, optionally under a different name. |
+
+### tag - snapshot tags (create, delete, protect)
+
+| Verb | Purpose |
+|---|---|
+| `create` | Tag a snapshot, optionally marking it protected. |
+| `delete` | Delete a tag. |
+| `protect` | Change a tag's protected flag. |
+
+### maintenance - managed maintenance policies and runs
+
+| Verb | Purpose |
+|---|---|
+| `policy` | Show the maintenance policy for a scope. |
+| `policy-upsert` | Create or update a maintenance policy. |
+| `policy-delete` | Delete a maintenance policy. |
+| `run` | Trigger a maintenance run. |
+| `runs` | List past maintenance runs. |
+
+### manifest - topology manifest export/import (YAML)
+
+| Verb | Purpose |
+|---|---|
+| `export` | Export the whole control-plane topology as YAML. |
+| `import` | Import a topology manifest (YAML) into the control plane. |
+
+### federation - federated sources per (tenant, tenant-db)
+
+| Verb | Purpose |
+|---|---|
+| `list` | List federated sources. |
+| `get` | Show one federated source. |
+| `create` | Create a federated source. |
+| `delete` | Delete a federated source. |
+| `secret list` | List secrets referenced by a federated source's setup SQL. |
+| `secret set` | Set a secret (inline value or external reference). |
+| `secret delete` | Delete a secret. |
+
+### audit - audit log
+
+| Verb | Purpose |
+|---|---|
+| `list` | List audit log entries with filters. |
+| `actions` | Distinct audit action names, for filter values. |
+
+### history - statement history and trends
+
+| Verb | Purpose |
+|---|---|
+| `statements` | List past statements with filters. |
+| `trends` | Aggregate statement trends over time. |
+
+## Output
+
+Human-readable Rich tables are the default. Pass `--json` (a top-level flag,
+before the noun) for the raw JSON response body - the stable interface for
+scripting. `qod sql` additionally supports `--csv`.
+
+Exit codes: `0` success, `1` a server/API error (the server's error body is
+shown verbatim, e.g. `tenant_forbidden`), `2` a usage error (missing or
+invalid arguments, the Typer/Click default).
+
+## SQL plane
+
+`qod sql "SELECT ..."` runs one statement and prints the result; `qod sql`
+with no statement argument opens an interactive REPL (statements end with
+`;`, `\q` or Ctrl-D exits, errors from one statement do not exit the REPL).
+
+Credentials for the FlightSQL edge are resolved in this order:
+
+1. `QOD_PASSWORD` environment variable
+2. `sql_password` in the active profile (opt-in; not written by `qod login`)
+3. An interactive prompt, once per invocation
+
+`sql_user` comes from `qod login` (or `QOD_USER`/`--tenant` overrides).
+`--superuser` sends the superuser call header instead of a tenant/pool pair.
+TLS to the edge defaults to on with certificate verification off, since the
+edge ships a self-signed certificate; set `edge_tls_verify = true` or
+`QOD_TLS_VERIFY=true` to opt into verification against a real certificate.

qod_cli-0.3.7/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qod-cli"
+dynamic = ["version"]
+description = "Command-line client for quack-on-demand: admin REST plane and FlightSQL plane"
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "httpx>=0.27",
+    "platformdirs>=4.0",
+    "tomli>=2.0; python_version < '3.11'",
+    "tomli-w>=1.0",
+    "adbc-driver-flightsql>=1.0",
+    "pyarrow>=16.0",
+    "pyreadline3>=3.4; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "respx>=0.21"]
+
+[project.scripts]
+qod = "qod_cli.main:main"
+
+[tool.hatch.version]
+path = "src/qod_cli/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qod_cli"]

qod_cli-0.3.7/src/qod_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.7"

qod_cli-0.3.7/src/qod_cli/commands/_run.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from ..output import render
+from ..rest import ApiError, RestClient
+
+
+def call(
+    ctx: typer.Context,
+    method: str,
+    path: str,
+    params: dict | None = None,
+    body: Any | None = None,
+    text: bool = False,
+) -> Any:
+    try:
+        data = RestClient(ctx.obj.settings).request(method, path, params=params, body=body, text=text)
+    except ApiError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1)
+    render(data, ctx.obj.json_output)
+    return data
+
+
+def kv_pairs(values: list[str] | None) -> dict:
+    out: dict = {}
+    for item in values or []:
+        if "=" not in item:
+            raise typer.BadParameter(f"expected KEY=VALUE, got {item!r}")
+        key, _, value = item.partition("=")
+        out[key] = value
+    return out

qod_cli-0.3.7/src/qod_cli/commands/auth.py

@@ -0,0 +1,67 @@
+from urllib.parse import urlparse
+
+import typer
+
+from ..config import save_profile
+from ..output import render
+from ..rest import ApiError, RestClient
+from ._run import call
+
+app = typer.Typer(help="Authentication mode discovery.")
+
+
+@app.command()
+def mode(ctx: typer.Context):
+    """Show the auth mode (db or oidc) the manager expects."""
+    call(ctx, "GET", "/api/auth/mode")
+
+
+def login(
+    ctx: typer.Context,
+    url: str = typer.Option(None, "--url", help="Manager URL; defaults to the profile value."),
+    username: str = typer.Option("admin", "--username"),
+    tenant: str = typer.Option(None, "--tenant", help="Tenant for tenant-scoped admins."),
+):
+    """Mint a session, store it and the edge settings in the active profile."""
+    settings = ctx.obj.settings
+    manager_url = url or settings.manager_url
+    password = typer.prompt("Password", hide_input=True)
+    settings.manager_url = manager_url
+    client = RestClient(settings)
+    body = {"username": username, "password": password}
+    if tenant is not None:
+        body["tenant"] = tenant
+    try:
+        login_resp = client.request("POST", "/api/auth/login", body=body)
+        edge = client.request("GET", "/api/config/client")
+    except ApiError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1)
+    edge_host = edge.get("flightSqlHost", "")
+    if edge_host in ("", "0.0.0.0"):
+        edge_host = urlparse(manager_url).hostname or "localhost"
+    save_profile(
+        ctx.obj.profile,
+        {
+            "manager_url": manager_url,
+            "token": login_resp["token"],
+            "sql_user": username,
+            "edge_host": edge_host,
+            "edge_port": edge.get("flightSqlPort", 31338),
+            "edge_tls": edge.get("flightSqlTls", True),
+        },
+    )
+    render(
+        {"username": login_resp.get("username", username), "profile": ctx.obj.profile},
+        ctx.obj.json_output,
+    )
+
+
+def logout(ctx: typer.Context):
+    """Revoke the current session token."""
+    call(ctx, "POST", "/api/auth/logout")
+
+
+def whoami(ctx: typer.Context):
+    """Verify the current session."""
+    call(ctx, "GET", "/api/auth/whoami")