diff --git a/skills/hotdata-analytics/references/WORKFLOWS.md b/skills/hotdata-analytics/references/WORKFLOWS.md index 17643f3..eb859d0 100644 --- a/skills/hotdata-analytics/references/WORKFLOWS.md +++ b/skills/hotdata-analytics/references/WORKFLOWS.md @@ -60,7 +60,7 @@ hotdata query "SELECT ..." hotdata query status ``` - Exit codes: `0` succeeded, `1` failed, `2` still running. + Exit codes: `0` succeeded, `1` failed, `2` still running, `3` succeeded but the result is an incomplete/truncated preview (the CLI fails closed so pipelines don't silently process partial data). ### 2. Materialize diff --git a/skills/hotdata-geospatial/SKILL.md b/skills/hotdata-geospatial/SKILL.md index bb61a16..a9d3d45 100644 --- a/skills/hotdata-geospatial/SKILL.md +++ b/skills/hotdata-geospatial/SKILL.md @@ -6,7 +6,7 @@ version: 0.9.0 # Hotdata Geospatial Skill -Hotdata supports a subset of PostGIS-style functions in **PostgreSQL-dialect SQL**. This skill is dataset-agnostic — apply it to any table with geometry columns. +Hotdata supports a subset of PostGIS-style functions in **PostgreSQL-dialect SQL**. This skill is data-agnostic — apply it to any table with geometry columns. **Requires the core `hotdata` skill** for auth, workspace, and table discovery. **Related:** **`hotdata-analytics`** (OLAP SQL), **`hotdata-search`** (BM25/vector). @@ -20,7 +20,7 @@ hotdata query "" [--workspace-id ] [--database ] [--output table|js - **Fully qualify tables** as `..` (or `..
` for a managed database) — every `
` placeholder below means a qualified name. - **PostgreSQL dialect:** double-quote any non-lowercase identifier (e.g. `"GeoID"`). -- Discover candidate tables/columns with **`hotdata tables list --connection-id `** (see core skill). +- Discover candidate tables/columns with **`hotdata tables list --connection-id `** (connection tables) or **`hotdata databases tables`** (tables inside a managed database) — see core skill. --- diff --git a/skills/hotdata-search/SKILL.md b/skills/hotdata-search/SKILL.md index 92de03b..6461bbd 100644 --- a/skills/hotdata-search/SKILL.md +++ b/skills/hotdata-search/SKILL.md @@ -43,7 +43,7 @@ hotdata search "" --table [--type vector] [--co ## Indexes (BM25 and vector) -Create attaches to a table via its `--catalog` alias (a managed-database catalog or a connection name). `list` filters by any of `--connection-id` / `--schema` / `--table` (all optional). `delete` **requires all of** `--connection-id` + `--schema` + `--table` + `--name`. +Create attaches to a table via its `--catalog` alias (a managed-database catalog or a connection name). `list` filters by any of `--connection-id` (short `-c`) / `--schema` / `--table` (all optional). `delete` **requires all of** `--connection-id` (short `-c`) + `--schema` + `--table` + `--name`. **Unscoped `hotdata indexes list` (no `--connection-id`) scans the whole workspace — both regular connections *and* managed databases** — so managed-database indexes appear without any flags. In that whole-workspace view the `table` column shows a managed database under its internal `__db_..
` label (a connection-scoped `indexes list --connection-id ` shows the same rows). @@ -61,7 +61,7 @@ hotdata indexes create --catalog --schema --table
\ hotdata indexes delete --connection-id --schema --table
--name ``` -- **`--type` is required** on create: `bm25` (one text column) or `vector` (exactly one column; often embeddings or auto-embedded text). (`sorted` is also a valid `--type`, covered in **`hotdata-analytics`**.) +- **`--type` is required** on create: `bm25` (one or more text columns, comma-separated in `--column`) or `vector` (exactly one column; often embeddings or auto-embedded text). (`sorted` is also a valid `--type`, covered in **`hotdata-analytics`**.) - **`sorted`** indexes (range/equality for OLAP filters) are documented in **`hotdata-analytics`** — this skill focuses on retrieval types. - **`--async`:** poll with `hotdata jobs ` (see **`hotdata`** skill **Jobs**). - **Auto-embedding:** `--type vector` on a **text** column generates embeddings server-side. Optional `--embedding-provider-id`; default output column `{column}_embedding` (override with `--output-column`). diff --git a/skills/hotdata/SKILL.md b/skills/hotdata/SKILL.md index 5013197..8c4c284 100644 --- a/skills/hotdata/SKILL.md +++ b/skills/hotdata/SKILL.md @@ -200,7 +200,7 @@ hotdata databases tables delete
[--database ] [--schema publ - `tables list` — lists tables with `TABLE` (`..
`), `SYNCED`, `LAST_SYNC`. Uses active database when `--database` is omitted. - `tables load` — uploads a local parquet file (`--file`), a remote parquet URL (`--url`), or a pre-staged upload (`--upload-id`) and publishes with **replace** mode. - `tables delete` — drops a table from the managed database. -- `run` — mints a database-scoped JWT (via `POST /v1/auth/database`) and execs `` with `HOTDATA_DATABASE_TOKEN`, `HOTDATA_DATABASE_REFRESH_TOKEN`, `HOTDATA_DATABASE`, `HOTDATA_WORKSPACE`, and `HOTDATA_API_URL` injected. Pass a database id as a group positional (`hotdata databases run ...`) or via `--database `; omit both to auto-create a scratch database using `--name` / `--schema` / `--table` / `--expires-at`. Use this to launch an agent or child process whose API access is scoped to a single database. The minted JWT carries `database`, `workspaces`, `permissions:["read","write"]`, `source:"database_token"`. The session is persisted at `~/.hotdata/database_session.json` (mode `0600`); the child's exit code is propagated. +- `run` — mints a database-scoped JWT (via `POST /v1/auth/database`) and execs `` with `HOTDATA_DATABASE_TOKEN`, `HOTDATA_DATABASE_REFRESH_TOKEN`, `HOTDATA_DATABASE`, `HOTDATA_WORKSPACE`, and `HOTDATA_API_URL` injected. Pass a database id as a group positional (`hotdata databases run ...`) or via `--database `; omit both to auto-create a scratch database using `--name` / `--schema` / `--table` / `--expires-at`. Use this to launch an agent or child process whose API access is scoped to a single database. The minted credential is a **database API token** (`source: database_api_token`, verifiable via `auth status`): it can only **create databases, run queries, and upload data**. Workspace-level operations — e.g. `databases list`/`show`, `connections`, `attach`/`detach`, listing other workspaces — return `403` and require a standard API key. The session is persisted at `~/.hotdata/database_session.json` (mode `0600`); the child's exit code is propagated. - `attach` — attaches a **connection** as a queryable catalog on a managed database, so the connection's **live** tables become visible inside that database's query scope. Defaults to the active database; target another with `--database`. `--alias` sets the SQL name the catalog answers to (defaults to the connection's name). This is how you query connection tables and **join across sources** — see [Querying across connections](#querying-across-connections-attach). - `detach` — removes an attached connection catalog. Accepts the connection name/id **or** the alias you attached it under. Defaults to the active database. - `create --attach [=]` — attach one or more connections at creation time (repeatable), e.g. `--attach github --attach salesdb=sales`. @@ -311,10 +311,12 @@ Bundled Markdown skills (**`hotdata`**, **`hotdata-search`**, **`hotdata-analyti ``` hotdata skills install [--project] hotdata skills status +hotdata skills list ``` - **`install`** — Downloads and installs skills to **`~/.hotdata/skills/`**, then symlinks into **`~/.agents/skills`** and into **`~/.claude/skills`** / **`~/.pi/skills`** when those directories exist. **`--project`** instead copies into **`./.agents/skills/`** in the current directory (and links `./.claude` / `./.pi` when present). The CLI may auto-refresh skills after an upgrade when appropriate. - **`status`** — Reports installed vs current CLI version and where skills are linked. +- **`list`** — Alias for `status`: lists installed skills, their versions, and where they are linked. ### Shell completions @@ -336,11 +338,15 @@ A newer release can be incompatible with the API, so in an **interactive termina ### Auth ``` -hotdata auth login # Browser-based login -hotdata auth status # Check current auth status -hotdata auth logout # Remove saved auth for the default profile +hotdata auth login # Browser-based login +hotdata auth register # Create a new account via browser (GitHub OAuth by default) +hotdata auth register --email # Create a new account via browser, using email + password instead of GitHub +hotdata auth status # Check current auth status +hotdata auth logout # Remove saved auth for the default profile ``` +`login` and `register` (both GitHub and `--email`) are **browser-based** PKCE flows: the CLI opens a browser and waits on a local callback to complete sign-in/sign-up — account details (email/password) are entered in the browser, not via CLI flags. They require a browser and an interactive terminal, so they do **not** work under `--no-input` or in headless/CI. For automation, authenticate once interactively, then use the saved session or `HOTDATA_API_KEY`. + ### Interactive connection wizard `hotdata connections new` creates a connection interactively (human-friendly); agents should prefer the programmatic `connections create` flow above. diff --git a/src/command.rs b/src/command.rs index 65172d2..26df21a 100644 --- a/src/command.rs +++ b/src/command.rs @@ -254,7 +254,8 @@ impl From for clap_complete::Shell { #[derive(Subcommand)] pub enum QueryCommands { /// Check the status of a running query and retrieve results. - /// Exit codes: 0 = succeeded, 1 = failed, 2 = still running (poll again) + /// Exit codes: 0 = succeeded, 1 = failed, 2 = still running (poll again), + /// 3 = succeeded but the result is an incomplete/truncated preview Status { /// Query run ID id: String,