Quick Start

Create a workspace, connect a database, optionally use sessions for exploratory work, upload files as datasets, list tables, and run a query — all from the CLI.

The CLI supports optional agent skills so coding assistants can discover and run hotdata commands safely. See Agent skills below and the hotdata-cli repository.

1) Install the CLI

Install walkthrough (YouTube):

brew install hotdata-dev/tap/cli

Verify the installation:

hotdata --help

2) Initialize and log in

Create the local config directory and authenticate via browser:

hotdata init
hotdata auth login

A browser window will open for you to sign in and authorize the CLI. Verify you're logged in:

hotdata auth status

Agent skills ship with hotdata-cli as machine-readable instructions (for example, under skills/hotdata-cli in that repo). They describe what the CLI can do, when to use it, and how—so tools such as Claude Code, Cursor, and other agents can invoke hotdata for you instead of you copying commands by hand.

Claude Code integration (YouTube):

Install or refresh the skill in your environment:

hotdata skills install

Check that the skill is present:

hotdata skills status

After installation, agents that support skills can list workspaces, run queries, manage connections, and follow the same workflows as the CLI—using your existing login and config (for example ~/.hotdata/config.yml). You stay in control: the CLI and API rules still apply; the skill mainly teaches the agent how to call them.

For command tables, global flags, and release notes, use the CLI --help output and the hotdata-cli README.

4) Create a workspace and connection

List available connection types before creating a connection:

hotdata connection-types list

Example output:

name        label
postgres    PostgreSQL
mysql       MySQL
snowflake   Snowflake
bigquery    Google BigQuery
duckdb      DuckDB

Create a workspace and add a Postgres (or other) connection in the Hotdata app. See Data Sources for supported types and setup notes.

You can think of workspaces as a security boundary between connections—each workspace is isolated from the others.

Once provisioned, list your workspaces to get the workspace ID:

hotdata workspace list

Note the workspace ID (e.g. ws_...) for the next steps.

5) Sessions (optional)

Sessions group ad-hoc CLI work in a workspace: queries, notes, and datasets you create while a session is active are tied to that session. Datasets created inside a session are removed when the session ends — use sessions for exploration; create datasets outside a session (see Upload data) when you need them to persist.

Sessions tutorial (YouTube):

Start a named session and set it active:

hotdata sessions new --name "Exploration" -w ws_abc123

Run a nested command with HOTDATA_SESSION and workspace set in the child process (typical for agents and multi-step workflows):

hotdata sessions run hotdata tables list --workspace-id ws_abc123

Record context in the session markdown as you go:

hotdata sessions update --markdown $'## Notes\n- Key tables: ...' -w ws_abc123

List sessions (* marks the active one), read the current session body, and see the full command surface in CLI Reference — Sessions.

6) Upload data

Upload CSV, JSON, or Parquet to create a dataset — a table you can query without a live connection. Datasets appear as datasets.main.<table_name> in SQL (see CLI Reference — Datasets).

Upload demo (YouTube):

From a file:

hotdata datasets create --file data.csv --label "My Dataset" --workspace-id ws_abc123

Optional --table-name sets the SQL table name; otherwise it is derived from the file. You can pipe stdin instead of --file:

cat data.csv | hotdata datasets create --label "My Dataset" --workspace-id ws_abc123

List datasets in the workspace:

hotdata datasets list --workspace-id ws_abc123

Use the table name from that output with datasets.main.<table_name> in hotdata query (see Execute SQL).

7) List connections

List connections for your workspace:

hotdata connections list <workspace_id>

Example:

hotdata connections list ws_abc123

8) List tables

List all tables in the workspace:

hotdata tables list <workspace_id>

To scope to a specific connection:

hotdata tables list <workspace_id> --connection-id <connection_id>

Example:

hotdata tables list ws_abc123 --connection-id conn_xyz789 --format table

9) Execute SQL

Run a query against your workspace:

hotdata query "<sql>" --workspace-id <workspace_id>

Base example:

hotdata query "SELECT 1 AS num" --workspace-id ws_abc123

Optional flags: --connection <connection_id> to scope to a connection, --format table|json|csv for output format. For keyword or semantic search without hand-written SQL, use hotdata search. Replace table and column names with those from your connected data sources.

Analytical functions

Analytical functions using window functions for rankings, running totals, and row comparisons:

hotdata query "
  SELECT id, amount,
    sum(amount) OVER (
      ORDER BY id
      ROWS BETWEEN UNBOUNDED PRECEDING
        AND CURRENT ROW
    ) AS running_total
  FROM transactions
  LIMIT 10
" --workspace-id ws_abc123

hotdata query "
  SELECT date, symbol, price,
    lag(price) OVER (
      PARTITION BY symbol
      ORDER BY date
    ) AS prev_price
  FROM stock_prices
" --workspace-id ws_abc123

Geospatial

Spatial queries using PostGIS-style functions:

hotdata query "
  SELECT id, name FROM stores
  WHERE ST_Distance(
    ST_GeomFromText('POINT(-122.4194 37.7749)'),
    location
  ) < 10000
" --workspace-id ws_abc123

Point search

Single-row lookups by primary key. Bloom filters enable efficient equality predicates for point lookups:

hotdata query "SELECT * FROM users WHERE id = 12345 LIMIT 1" --workspace-id ws_abc123

Full text search

Requires a full-text index on the text column. After hotdata indexes create ... --type bm25, run hotdata indexes list for that table: in terminals that support command links, you can use the clickable shortcut next to the index to run hotdata search with the right --table and --column.

hotdata search (same idea as the link target):

hotdata search "machine learning" \
  --table conn.public.articles \
  --column body \
  --select id,title,body \
  --limit 10 \
  --workspace-id ws_abc123

Equivalent SQL with hotdata query (same search as hotdata search for a single column; add columns with SELECT as needed):

hotdata query "
  SELECT id, title, body, score
  FROM bm25_search('conn.public.articles', 'body', 'machine learning')
  ORDER BY score DESC LIMIT 10
" --workspace-id ws_abc123

Vector search

Requires a vector index. hotdata indexes list can expose the same style of command link for vector indexes; use it to run hotdata search with the embedding column prefilled.

Vector search demo (YouTube):

hotdata search with --model (embeds the query via OpenAI; set OPENAI_API_KEY):

hotdata search "documents about machine learning" \
  --table conn.public.documents \
  --column embedding \
  --model text-embedding-3-small \
  --limit 10 \
  --workspace-id ws_abc123

Equivalent SQL with hotdata query when you already have a query vector (approximate nearest-neighbor via datafusion-vector-search-ext; ORDER BY distance_fn(column, query_vector) ASC LIMIT k is rewritten to HNSW when the pattern matches):

hotdata query "
  SELECT id, title,
    l2_distance(embedding, ARRAY[0.1, -0.2, 0.5]) AS dist
  FROM documents
  ORDER BY dist ASC LIMIT 10
" --workspace-id ws_abc123

For cosine similarity, use cosine_distance; for inner product, use negative_dot_product.