CLI Reference

Command line interface for Hotdata.

Install

Homebrew

brew install hotdata-dev/tap/cli

Shell (macOS, Linux)

curl -fsSL https://github.com/hotdata-dev/hotdata-cli/releases/latest/download/hotdata-cli-installer.sh | sh

Update

hotdata upgrade

Connect

Authenticate via browser:

hotdata auth

This launches a browser window where you can sign in and authorize the CLI. To create a new account:

hotdata auth register

Verify you're logged in:

hotdata auth status

Alternatively, pass an API key directly:

hotdata <command> --api-key <api_key>

Or set the HOTDATA_API_KEY environment variable (also loaded from .env files):

export HOTDATA_API_KEY=<api_key>
hotdata <command>

API key priority (lowest to highest): config file → HOTDATA_API_KEY env var → --api-key flag.

Commands

Global options

Workspaces

hotdata workspaces list
hotdata workspaces set [<workspace_id>]

• list shows all workspaces with a * marker on the active one.
• set switches the active workspace. Omit the ID for interactive selection.
• The active workspace is used as the default for all commands that accept -w.

Connections

hotdata connections list [-w <id>] [-o table|json|yaml]
hotdata connections <connection_id> [-w <id>] [-o table|json|yaml]
hotdata connections refresh <connection_id> [-w <id>]
hotdata connections new [-w <id>]

• list returns id, name, source_type for each connection.
• Pass a connection ID to view details.
• refresh triggers a schema refresh for a connection.
• new launches an interactive connection creation wizard.

Create a connection

# List available connection types
hotdata connections create list

# Inspect schema for a connection type
hotdata connections create list <type_name> --output json

# Create a connection
hotdata connections create \
  --name "my-conn" \
  --type postgres \
  --config '{"host":"...","port":5432,...}'

Tables

hotdata tables list \
  [-w <id>] \
  [--connection-id <id>] \
  [--schema <pattern>] \
  [--table <pattern>] \
  [--limit <n>] \
  [--cursor <token>] \
  [-o table|json|yaml]

• Without --connection-id: lists all tables across connections with table, synced, last_sync.
• With --connection-id: includes column details (column, data_type, nullable).
• --schema and --table support SQL % wildcard patterns.
• Tables are addressed as <connection>.<schema>.<table> in SQL queries.

Databases

Managed databases are Hotdata-owned catalogs you populate with parquet files. Tables are addressed as <catalog>.<schema>.<table> in SQL, where <catalog> is the alias set with --catalog at create time.

hotdata databases list [-w <id>] [-o table|json|yaml]
hotdata databases show <name_or_id> [-w <id>]
hotdata databases create \
  [--catalog <alias>] \
  [--name <label>] \
  [--table <name>]... \
  [--schema <schema>] \
  [--attach <connection[=alias]>]... \
  [--expires-at <duration>] \
  [-w <id>]
hotdata databases attach <connection> [-d <name_or_id>] [--alias <alias>]
hotdata databases detach <connection> [-d <name_or_id>]
hotdata databases set <name_or_id>
hotdata databases unset
hotdata databases delete <name_or_id>

• list shows all databases with their ID and description.
• show displays ID, description, default connection, and attached catalogs.
• create creates a new database. --catalog sets the SQL alias (SELECT … FROM <alias>.schema.table); must be [a-z_][a-z0-9_]* and globally unique. --name is a free-form display label. --table (repeatable) declares tables up front and accepts schema.table dot notation to span schemas. --schema sets the default schema for bare --table entries (default public). --attach (repeatable) attaches a connection as a queryable catalog on the new database; accepts a connection name or id, optionally connection=alias to set the SQL alias (--attach github --attach salesdb=sales). --expires-at accepts a relative duration (24h, 7d, 90m) or RFC 3339 timestamp; omitting it means the database never expires.
• set marks a database as the default for subsequent commands; unset clears it.
• delete removes the database and all its tables.

Attach a connection as a catalog

hotdata databases attach <connection> [-d <name_or_id>] [--alias <alias>]
hotdata databases detach <connection> [-d <name_or_id>]

• attach makes a connection's live tables visible inside a managed database's query scope, so you can join across sources in a single query without exporting data. Reachable in SQL as <alias>.<schema>.<table>, or <connection-name>.<schema>.<table> when --alias is omitted.
• -d/--database selects the database to attach into (defaults to the current database).
• detach removes a previously attached connection catalog.

Load parquet into a table

hotdata databases load --catalog <alias> --table <table> --file <path.parquet>
hotdata databases load --catalog <alias> --table <table> --url <https://...>
hotdata databases load --catalog <alias> --table <table> --upload-id <id>

• --catalog is the alias set at create time.
• --file uploads from a local path; --url downloads a remote parquet file; --upload-id uses a pre-staged upload from POST /v1/files.
• Load replaces the table contents on each call.
• If the table was not declared at create time, the CLI auto-redeclares the database with the table added and retries the load.

Manage tables

hotdata databases tables [<database>] [-o table|json|yaml]
hotdata databases tables load --catalog <alias> --table <table> --file <path.parquet>
hotdata databases tables delete <table> [--database <name_or_id>]

• tables (or tables list) lists the tables in a database.
• tables load is equivalent to databases load — it creates or replaces a table from parquet.
• tables delete removes a table from the database.

Query a managed database

Pass --database to scope a query to a specific managed database:

hotdata query "SELECT * FROM mydb.public.orders LIMIT 10"

Run a command with a database-scoped token

databases run executes a command with a short-lived, database-scoped token in its environment. Omit --database to auto-create an ephemeral database (default --expires-at 24h) for the duration of the work — useful for agent and CI workflows.

# Scope a command to an existing database
hotdata databases run --database <name_or_id> -- <command>...

# Auto-create a throwaway database, declare tables, then run
hotdata databases run \
  --name "scratch" \
  --table orders \
  --expires-at 24h \
  -- <command>...

Query

hotdata query "<sql>" \
  [-w <id>] \
  [--database <name_or_id>] \
  [-o table|json|csv]
hotdata query status <query_run_id>

• Default output is table, which prints results with row count and execution time.
• Use --database to query a managed database (<catalog>.<schema>.<table> in SQL).
• Long-running queries fall back to async execution and return a query_run_id.
• Use hotdata query status <query_run_id> to poll for results.
• Exit codes for query status: 0 = succeeded, 1 = failed, 2 = still running.

Query Run History

hotdata queries list \
  [--limit <n>] \
  [--cursor <token>] \
  [--status <csv>] \
  [-o table|json|yaml]
hotdata queries <query_run_id> [-o table|json|yaml]

• list shows past query executions with status, creation time, duration, row count, and a truncated SQL preview (default limit 20).
• --status filters by run status (comma-separated, e.g. --status running,failed).
• View a run by ID to see full metadata (timings, result_id, SQL).
• Retrieve rows for a completed run with hotdata results <result_id>.

Search

# Full-text search (requires a BM25 index on the column)
hotdata search "query text" \
  --table <connection.schema.table> \
  [--column <column>] \
  [--select <columns>] \
  [--limit <n>] \
  [-o table|json|csv]

# Vector search (requires a vector index; server resolves model and embedding column)
hotdata search "query text" \
  --table <connection.schema.table> \
  --type vector \
  [--column <source_text_column>] \
  [--limit <n>]

• --type is optional when the table has exactly one search index — inferred automatically. Required when multiple indexes exist.
• --column is optional when the table has exactly one indexed column of the resolved type.
• For --type vector, --column names the source text column; the server resolves the embedding column and model from the index metadata.
• Full-text results are ordered by relevance score (descending). Vector results are ordered by distance (ascending).
• --select specifies columns to return (comma-separated, defaults to all).

Indexes

# Create on a managed database table (--catalog alias)
hotdata indexes create \
  --catalog <alias> --table <table> --column <col[,col...]> \
  --type bm25|vector|sorted \
  [--schema <schema>] \
  [--metric l2|cosine|dot] \
  [--embedding-provider-id <id>] \
  [--dimensions <n>] \
  [--output-column <name>] \
  [--description "..."] \
  [--async]

# List (whole workspace by default; narrow with filters)
hotdata indexes list \
  [--connection-id <id>] [--schema <s>] [--table <t>] \
  [-w <id>] [-o table|json|yaml]

# Delete by name — pass connection scope (--connection-id + --schema + --table)
hotdata indexes delete --connection-id <id> --schema <s> --table <t> --name <name>

• --type is required: bm25 (full-text), vector (similarity), or sorted (range/equality filters).
• --column takes one or more comma-separated columns; the index name is derived from table, columns, and type when --name is omitted.
• --metric is optional for vector indexes (l2, cosine, or dot).
• --embedding-provider-id enables automatic server-side embedding generation on a text column (defaults to the first system provider). --dimensions overrides the embedding output dimensions, and --output-column names the generated embedding column (default {column}_embedding).
• --description attaches a human-readable note to the embedding (e.g. "product titles").
• --async submits index creation as a background job; poll with hotdata jobs <job_id>.

Embedding providers

Embedding providers power automatic embedding generation for vector indexes.

hotdata embedding-providers list [-w <id>] [-o table|json|yaml]
hotdata embedding-providers get <id> [-w <id>]
hotdata embedding-providers create \
  --name <name> \
  --provider-type local|service \
  [--config '{"model":"..."}'] \
  [--provider-api-key <key>] \
  [-w <id>]
hotdata embedding-providers update <id> \
  [--name <name>] \
  [--config '{"model":"..."}'] \
  [-w <id>]
hotdata embedding-providers delete <id> [-w <id>]

• --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.

Context

Sync named Markdown context files with a managed database. Useful for giving agents persistent notes and schema documentation scoped to a database.

hotdata context list [-w <id>] [-d <database_id>]
hotdata context show <name> [-w <id>] [-d <database_id>]
hotdata context pull <name> [--force] [-w <id>] [-d <database_id>]
hotdata context push <name> [-w <id>] [-d <database_id>]

• list shows all named contexts stored in the database.
• pull downloads context to ./<NAME>.md. Use --force to overwrite an existing file.
• push uploads ./<NAME>.md to the database as named context.
• <name> is case-insensitive; a trailing .md is ignored (e.g. USER.md → USER).

Results

hotdata results <result_id> [-w <id>] [-o table|json|csv]
hotdata results list [-w <id>] [--limit <n>] [--offset <n>] [-o table|json|yaml]

• Every query result is stored automatically — use result-id from the table footer to retrieve it without re-running.

Usage

hotdata usage [-w <id>] [--since <rfc3339>] [-o table|json|yaml]

• 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.

Jobs

hotdata jobs list \
  [-w <id>] \
  [--job-type <type>] \
  [--status <status>] \
  [--all] \
  [--limit <n>] \
  [--offset <n>] \
  [-o table|json|yaml]
hotdata jobs <job_id> [-w <id>] [-o table|json|yaml]

• list shows only active jobs (pending and running) by default. Use --all to see all jobs.
• --job-type accepts: data_refresh_table, data_refresh_connection, create_index.
• --status accepts: pending, running, succeeded, partially_succeeded, failed.

Skills

hotdata skills install
hotdata skills status

Installs or refreshes the hotdata agent skill into agent directories (Claude Code, Cursor, etc.). See Quick Start — Agent skills.

Configuration

Config is stored at ~/.hotdata/config.yml keyed by profile (default: default).

See also

• Quick Start — Install, authenticate, and run your first query
• API Reference — Full HTTP API documentation
• Data Sources — Supported connection types