# CLI Reference Source: https://www.hotdata.dev/docs/cli-reference Site index: https://www.hotdata.dev/llms.txt ## Install **Homebrew** ```sh brew install hotdata-dev/tap/cli ``` **Shell (macOS, Linux)** ```sh curl -fsSL https://github.com/hotdata-dev/hotdata-cli/releases/latest/download/hotdata-cli-installer.sh | sh ``` **From source** (requires Rust) ```sh cargo install --path . ``` Or download a binary from [Releases](https://github.com/hotdata-dev/hotdata-cli/releases). Update with `hotdata manage upgrade`. ## Connect Authenticate via browser: ```sh hotdata auth login ``` This launches a browser window where you can sign in and authorize the CLI. To create a new account: ```sh hotdata auth register # GitHub OAuth; add --email for email + password ``` Check status or sign out: ```sh hotdata auth status hotdata auth logout ``` Alternatively, pass an API key directly: ```sh hotdata --api-key ``` Or set the `HOTDATA_API_KEY` environment variable (also loaded from `.env` files): ```sh export HOTDATA_API_KEY= hotdata ``` API key priority (lowest to highest): config file → `HOTDATA_API_KEY` env var → `--api-key` flag. ## Command reference The full command surface. The top level has eight groups — `auth`, `workspaces`, `databases`, `query`, `jobs`, `ingest`, `search`, and `manage`. Run `hotdata --help` for the complete flags on any of them. | Command | Description | | :-- | :-- | | `auth login` | Log in via browser | | `auth register` | Create a new account via browser (GitHub OAuth; `--email` for email + password) | | `auth logout` | Remove authentication for a profile | | `auth status` | Show authentication status | | `workspaces list` | List all workspaces | | `workspaces use` | Set the default workspace | | `databases list` | List instant databases in the workspace | | `databases count` | Count instant databases in the workspace | | `databases show` | Show details for an instant database | | `databases create` | Create a new instant database | | `databases fork` | Fork a database into a new, independent database | | `databases attach` | Attach a catalog so its tables are queryable | | `databases detach` | Detach a previously attached catalog | | `databases use` | Set the current (default) database | | `databases unset` | Clear the current database | | `databases remove` | Delete a database and all its tables | | `databases load` | Load a parquet file or saved result into a table | | `databases tables list` | List tables in a database | | `databases tables show` | Show column definitions for a table | | `databases tables load` | Load parquet/result into a table (create or replace) | | `databases tables remove` | Delete a table from a database | | `databases context list` | List named contexts in a database | | `databases context show` | Print context content to stdout | | `databases context pull` | Download context to `./.md` | | `databases context push` | Upload `./.md` as named context | | `databases query` | Execute a SQL query against a database | | `databases query status` | Check a running query and retrieve results | | `databases queries list` | List query runs | | `databases results get` | Show a stored query result by ID | | `databases results list` | List stored query results | | `query ""` | Execute a SQL query (shortcut for `databases query`) | | `query status` | Check a running query and retrieve results | | `jobs list` | List background jobs (active by default) | | `jobs ` | Show one background job | | `ingest create` | Create a load definition | | `ingest list` | List the ingests in the workspace | | `ingest show` | Show one ingest: state, selector, destination, schedule | | `ingest pause` | Stop an ingest (cancel the active run and future runs) | | `ingest resume` | Clear a stop and let the schedule dispatch again | | `ingest schedule` | Change when a scheduled/continuous ingest runs next | | `ingest logs` | List the runs of one ingest | | `ingest run` | Show one run: status, snapshots, timings | | `ingest remove` | Delete an ingest and release its destination table | | `ingest sources test` | Check a config and credentials without creating anything | | `ingest sources add` | Create a datasource and its first config version | | `ingest sources list` | List the datasources in the workspace | | `ingest sources show` | Show one datasource: state, config, discovery | | `ingest sources update-config` | Append a config version (rotate credentials) | | `ingest sources remove` | Delete a datasource | | `ingest sources types` | Browse the catalog of source types | | `ingest sources fields` | Show the fields a source family accepts | | `search "" --index ` | Run a full-text or vector search against an index | | `search create` | Create a search index over a table column | | `search list` | List search indexes | | `search show` | Show one search index by name | | `search remove` | Remove a search index by name | | `search embeddings list` | List embedding providers | | `search embeddings show` | Show one embedding provider | | `search embeddings add` | Create a new embedding provider | | `search embeddings update` | Update an embedding provider | | `search embeddings remove` | Delete an embedding provider | | `manage usage` | Show workspace usage: queries, bytes scanned, stored bytes | | `manage completions` | Generate shell completions (`bash`, `zsh`, `fish`) | | `manage upgrade` | Upgrade the CLI to the latest release | | `manage skills install` | Install/update the agent skill into agent directories | | `manage skills status` | Show the agent skill's installation status | | `manage skills list` | List installed skills (alias for `status`) | ## Global options | Option | Description | | :-- | :-- | | `--api-key ` | API key (overrides env var and config) | | `--no-input` | Disable interactive prompts; error instead | | `-v, --version` | Print version | | `-h, --help` | Print help | Most commands also accept `-w, --workspace-id ` and `-o, --output `. Four commands trade `yaml` for `csv` — they accept `table\|json\|csv` and never `yaml`: `query`, `databases query`, `search ""`, and `databases results get`. Note that `databases results list` is not one of them; it stays on `table\|json\|yaml`. `query status`, `databases query status`, and `search create` take no `-o` at all. ## Workspaces ```sh hotdata workspaces list hotdata workspaces use [] ``` - `list` shows all workspaces with a `*` marker on the active one. - `use` switches the active workspace. Omit the ID for interactive selection. - The active workspace is the default for all commands that accept `-w`. ## Databases Instant databases are Hotdata-owned catalogs you populate with parquet files. Tables are addressed as `..` in SQL, where `` is the alias set with `--catalog` at create time. ```sh hotdata databases list [--limit ] [--cursor ] [-o table|json|yaml] hotdata databases count hotdata databases show hotdata databases create \ [--catalog ] \ [--name
`, or `..
` when `--alias` is omitted. - `-d/--database` selects the database to attach into (defaults to the current database). - `detach` removes a previously attached catalog. ### Load parquet into a table ```sh hotdata databases load --catalog --table
--file hotdata databases load --catalog --table
--url hotdata databases load --catalog --table
--upload-id hotdata databases load --catalog --table
--result-id ``` - `--catalog` is the alias set at create time; `--schema` defaults to `public`. - Sources: `--file` uploads from a local path; `--url` downloads a remote parquet file; `--upload-id` uses a pre-staged upload from `POST /v1/uploads`; `--result-id` loads a saved query result (which must belong to the target database). - Load replaces the table contents on each call. ### Manage tables ```sh hotdata databases tables [] hotdata databases tables list [--database ] [--schema

] [--table

] [--limit ] hotdata databases tables show hotdata databases tables load

[--database ] [--schema ] (--file|--url|--upload-id|--result-id) hotdata databases tables remove
[--database ] [--schema ] ``` - `tables` (or `tables list`) lists the tables in a database; `--database` defaults to the current database. - `show` prints column definitions for `catalog.schema.table` (or `schema.table` with an active database). - `tables load` creates or replaces a table from parquet or a saved result, addressing the database by `--database` rather than by `--catalog`. - `tables remove` drops a table from the database. ### Context Sync named Markdown context files with an instant database — persistent notes and schema documentation scoped to a database, useful for giving agents durable context. ```sh hotdata databases context list [-d ] [--prefix

] hotdata databases context show [-d ] hotdata databases context pull [--force] [--dry-run] [-d ] hotdata databases context push [--dry-run] [-d ] ``` - `pull` downloads context to `./.md` (`--force` overwrites an existing file); `push` uploads `./.md` to the database as named context. - `` follows SQL identifier rules; a trailing `.md` is ignored (e.g. `USER.md` → `USER`). ### Query run history & results ```sh hotdata databases queries list [--status ] [--limit ] [--cursor ] hotdata databases queries hotdata databases results list [--limit ] [--offset ] hotdata databases results get [-o table|json|csv] ``` - `queries list` shows past runs with status, timing, row count, and a truncated SQL preview (default limit 20); `--status` filters by run status (comma-separated, e.g. `running,failed`). View a run by ID for full metadata (timings, `result_id`, SQL). - Every query result is stored automatically — retrieve rows with `results get ` (the `result-id` printed in a query's footer) without re-running the query. ## Query `query` is a top-level shortcut into `databases query`. ```sh hotdata query "" \ [-d ] \ [--dialect hotsql|duckdb|postgres|snowflake] \ [-o table|json|csv] hotdata query status ``` - Default output is `table`, which prints results with row count and execution time. - `-d/--database` runs against a specific instant database (defaults to the current database set via `databases use`). It is sent as the `X-Database-Id` header, so it takes the database **id** — it does not resolve a name or catalog alias. - `--dialect` names the SQL the query is written in. Anything other than `hotsql` (the default) is transpiled to HotSQL server-side before it runs — read-only queries only. See [SQL dialects](/docs/sql#sql-dialects). - Long-running queries fall back to async execution and return a `query_run_id`. Poll it with `hotdata query status `. - Exit codes for `query status`: `0` succeeded, `1` failed, `2` still running (poll again), `3` succeeded but the result is a truncated preview. ## Ingest An **ingest** is a saved load definition: it reads from an external **source** and writes rows into an instant database. Add the source first (`hotdata ingest sources add`), then create an ingest that reads it. Selector and destination are fixed at creation; creating an ingest starts nothing — the scheduler dispatches every run, so watch it with `hotdata ingest logs ` rather than expecting a run id back. ```sh # Create a load definition (source + what to read + where it lands) hotdata ingest create --source --sql "SELECT * FROM .

" --database-id hotdata ingest create --source --all --database-id hotdata ingest create --source --table ... --type scheduled --every 1h --database-id # Inspect and control ingests hotdata ingest list [--datasource-id ] [--type ] [--state ] hotdata ingest show hotdata ingest logs [] [--status ] [--wait] [--wait-timeout ] hotdata ingest run [--wait] hotdata ingest pause hotdata ingest resume hotdata ingest schedule [--every ] [--next now|] hotdata ingest remove ``` - `create` needs a `--source` (a `ds_…` id or a display name) and a selector. Selector shorthands: `--sql` (SQL sources: `SELECT FROM [.]
[WHERE …] [LIMIT n]`), `--raw-sql` (a verbatim query in the source's own dialect), `--all`, `--table`/`--topic`/`--table-path` (per family), or `--selector` for raw family JSON. Destination flags: `--database-id`, `--dest-table` / `--dest-table-prefix`, `--dest-schema` (default `public`), and `--write-mode replace|upsert`. `--type` is `one-time` (default), `scheduled`, or `continuous` (`--stream`); recurring types need `--every` or `--schedule`. - There is no `run-now` verb — bring a run forward with `hotdata ingest schedule --next now`. - `pause` cancels the active run and stops future ones; `resume` clears the stop but runs nothing immediately (one-time ingests can't be resumed — create a new one). - `logs` lists an ingest's runs (newest first); `run ` shows one run. Both accept `--wait` to watch until a terminal state (exit `0` succeeded, `1` failed/cancelled, `2` still queued/running). - `remove` soft-deletes the ingest and releases its destination table; the table, its data, and the source are never deleted. ### Sources A **source** (datasource) stores an external system's connection config and credentials. It's surfaced under `ingest sources` so a source and the ingests that read it share one command tree. ```sh hotdata ingest sources types [] hotdata ingest sources fields [] hotdata ingest sources test --family [--config ] [--credentials ] [--bucket-url ] hotdata ingest sources add [--family ] [--display-name ] [--config ] [--credentials ] hotdata ingest sources list [--family ] [--state ] hotdata ingest sources show hotdata ingest sources update-config [--config ] [--credentials ] hotdata ingest sources remove ``` - Families: `sql`, `rest`, `filesystem`, `iceberg`, `delta`, `ducklake`, `kafka`, `derived`. Use `sql` for any SQL dialect (the dialect goes in the config), `filesystem` for buckets, and `derived` to build a table from another table in your own workspace. `hotdata ingest sources fields` prints the list with each family's required config. - `types` browses the catalog of source types and their families; `fields ` shows the config, credentials, and selector fields a family accepts (generated by the service, so it matches exactly what the API accepts). - `test` checks a config and credentials without creating anything — `valid` means the shape was accepted, `probed` means the source was actually contacted. - `add` returns a stable `ds_…` id and loads no data; on a terminal it prompts for the source type and fields (skip with `--no-input` and `--config`). Config and credentials are JSON — inline, `@file.json`, or `@-` for stdin; keep secrets out of argv with `@file`. - `update-config` appends a config version — rotate credentials by passing the same config plus new `--credentials`. - `remove` soft-deletes a source; its ingests must be removed first. ## Search Full-text (BM25) and vector search over an indexed table column, plus index and embedding-provider management. ```sh hotdata search "" \ --index \ [-d ] \ [--select ] \ [--limit ] \ [-o table|json|csv] ``` - The search type (full-text vs vector) is inferred from the index. `--index` addresses the index by name (from `hotdata search list`); `-d/--database` is the database the index lives in (defaults to the active database). - Full-text results are ordered by relevance (descending); vector results by distance (ascending). `--select` limits the returned columns (comma-separated, defaults to all). ### Manage indexes ```sh hotdata search create [] --type text|vector|sorted --from --column \ [--metric l2|cosine|dot] \ [--provider ] \ [--dimensions ] [--output-column ] [--description "..."] \ [--async] hotdata search list [--schema ] [--table ] hotdata search show [-d ] hotdata search remove [-d ] ``` - `--type`: `text` (BM25 full-text), `vector` (similarity), or `sorted` (range/equality filters). The index name is derived from table, column, and type when omitted. - `--metric` applies to vector indexes. `--provider` enables server-side auto-embeddings on a text column; `--dimensions` overrides the embedding output dimensions and `--output-column` names the generated column (default `{column}_embedding`). - `--type` values are not freely combinable. An index created with `--provider` (auto-embedding vector) must be the only index on its table: creating one fails if the table already has an index, and no other index can be added while it exists. A `vector` index over an existing embedding column carries no such restriction, so it coexists with `text` and `sorted` indexes. See [vector indexes](/docs/sql#vector-indexes). - `--async` submits index creation as a background job — poll with `hotdata jobs `. ### Embedding providers Embedding providers are the models behind vector search. ```sh hotdata search embeddings list hotdata search embeddings show hotdata search embeddings add --name --provider-type local|service \ [--config '{"model":"..."}'] \ [--provider-api-key | --secret-name ] hotdata search embeddings update [--name ] [--config ] [--provider-api-key | --secret-name ] hotdata search embeddings remove ``` - `--provider-type local` uses a local embedding model; `service` calls an external API (e.g. OpenAI). - `--provider-api-key` auto-creates a managed secret for the provider's API key; `--secret-name` references an existing secret instead. ## Jobs ```sh hotdata jobs list \ [--job-type ] \ [--status ] \ [--all] \ [--limit ] [--offset ] \ [-o table|json|yaml] hotdata jobs ``` - `list` shows only active jobs (`pending` and `running`) by default; use `--all` to see every job. - `--job-type` accepts: `data_refresh_table`, `data_refresh_connection`, `create_index`, `managed_load`. - `--status` accepts: `pending`, `running`, `succeeded`, `partially_succeeded`, `failed`. ## Manage Account, configuration, and CLI maintenance. ```sh hotdata manage usage [--since ] [-o table|json|yaml] hotdata manage completions bash|zsh|fish hotdata manage upgrade hotdata manage skills install [--project] hotdata manage skills status ``` - `usage` shows workspace usage: query count, bytes scanned, and stored bytes. `--since` counts usage from an RFC 3339 timestamp (e.g. `2026-06-01T00:00:00Z`); defaults to the current billing window. - `completions` prints a shell completion script; `upgrade` updates the CLI to the latest release. - `skills install` installs or refreshes the hotdata agent skill into agent directories (Claude Code, Cursor, etc.); `--project` installs into the current project instead of globally. See [Agent Skills](/docs/agent-skills). ## Configuration Config is stored at `~/.hotdata/config.yml`, keyed by profile (default: `default`). Override the config directory with `HOTDATA_CONFIG_DIR`. | Variable | Description | | :-- | :-- | | `HOTDATA_API_KEY` | API key (overrides the config file) | | `HOTDATA_WORKSPACE` | Default workspace ID for the current process | | `HOTDATA_DATABASE` | Default instant database for the current process | | `HOTDATA_API_URL` | Override the API endpoint (default `https://api.hotdata.dev/v1`) | | `HOTDATA_APP_URL` | Override the app URL used for browser auth | ## See also - [Quick Start](/docs/quick-start) — Install, authenticate, and run your first query - [API Reference](/docs/api-reference) — Full HTTP API documentation - [Pull Data](/docs/pull-data) — Supported source types