CLI reference

The hypequery CLI provides commands for scaffolding, generating types, and running development servers. Remote ClickHouse workflows use credentials collected during init or supplied through the CLICKHOUSE_* environment variables below. The chdb driver runs on embedded ClickHouse and needs no server credentials.

Which command should I use?

Use the CLI commands for different jobs:

The most common confusion is between init and generate:

• init scaffolds a project structure
• generate refreshes schema types from your current ClickHouse database

If you have already created your analytics folder and only need updated types, run hypequery generate.

Installation

No installation required! Run commands directly with npx:

npx @hypequery/cli init
npx @hypequery/cli dev

For frequent use, install as a dev dependency:

npm install -D @hypequery/cli
# or
pnpm add -D @hypequery/cli

Then use the shorter hypequery command:

npx hypequery init
npx hypequery dev

TypeScript support

hypequery dev can load .ts and .tsx query files directly. The CLI bundles your entry file in-process before importing it, so no separate TypeScript runtime is required. If you already compile to JavaScript, you can still target the generated .js file instead.

Commands at a glance

The sections below expand on the supported options and expected behavior for each command.

hypequery telemetry

The CLI sends pseudonymous usage events to https://hypequery.com/api/telemetry unless telemetry is disabled. HYPEQUERY_TELEMETRY_DEBUG=1 prints validated events to stderr instead of sending; HYPEQUERY_TELEMETRY_URL sends to a staging or self-hosted first-party ingest endpoint instead. Opt-outs apply in every mode. See the telemetry reference for the event contract and delivery limits.

hypequery telemetry          # Same as telemetry status
hypequery telemetry disable # Save an opt-out
hypequery telemetry enable  # Save an opt-in
hypequery init --no-telemetry # Disable for one invocation

Status reports the effective setting, the source that determined it, and the random install ID. enable changes the saved preference; environment variables and the global flag still take precedence.

The first matching setting wins: --no-telemetry, DO_NOT_TRACK=1, HYPEQUERY_TELEMETRY_DISABLED=1, test environments (VITEST or NODE_ENV=test) and hypequery's own GitHub Actions CI, then the saved preference. The default preference is enabled, including in customer CI. Unavailable or corrupt settings disable telemetry for that invocation. An explicit enable or disable can repair corrupt settings; a failed save reports an error and the temporary opt-out options.

Settings live in telemetry.json beside the CLI's Cloud profile: macOS Application Support, Windows APPDATA (or LOCALAPPDATA), or Linux XDG_CONFIG_HOME (otherwise ~/.config/hypequery). HYPEQUERY_CONFIG_DIR overrides the directory.

hypequery init

# Without installation
npx @hypequery/cli init [options]

# With installation
npx hypequery init [options]

Options:

• --path <dir> – Target directory for the scaffold (client.ts, schema.ts, and either queries.ts or datasets.ts/api.ts). Defaults to analytics/
• --style <style> – Scaffold style: queries (default — query-builder routes) or datasets (semantic datasets API)
• --auth <mode> – Auth scaffold mode: none (default) or context (adds host/user context auth helpers)
• --all-tables – With --style datasets, generate dataset definitions for every discovered table
• --tables <names> – With --style datasets, generate datasets only for these comma-separated tables
• --exclude-tables <names> – With --style datasets, exclude these comma-separated tables from generation
• --no-example – Skip generating the sample query
• --database <type> – Database driver: clickhouse (default) or chdb to scaffold onto embedded ClickHouse — no server or credentials, and no .env is created or updated
• --chdb-path <path> – With --database chdb, the directory the embedded session stores data in (e.g. ./analytics.chdb); omit for an in-memory session. Reuse the same flag when later generate commands must see tables created by another process
• --no-interactive – Skip prompts and read the ClickHouse URL/database/user/password from CLICKHOUSE_* env vars. The command fails if any required variable is missing. With --database chdb there are no connection variables to read
• --force – Overwrite existing files without asking
• --skip-connection – Skip the initial database connectivity test and scaffold files without validating the selected driver first

What it does:

For the default clickhouse driver, the CLI validates the remote connection using the credentials you provide. For chdb, it installs and starts the embedded engine against the selected storage path. On success it:

• Writes remote ClickHouse credentials to .env; chDB writes no connection configuration because later commands use explicit driver and path flags
• Generates client.ts, schema.ts, and queries.ts (or datasets.ts + api.ts with --style datasets) in the selected directory
• Creates or updates .gitignore to protect secrets
• Installs the scaffold dependencies the generated files expect (@hypequery/clickhouse, @hypequery/serve, zod, plus @hypequery/datasets for the datasets style and chdb for the embedded driver) using the package manager detected in your project
• Prints follow-up instructions for hypequery dev

With a valid connection, interactive mode can generate a table-backed example after you select a table. Otherwise the query scaffold contains a database-independent exampleMetric. To skip the automatic dependency install (for example in CI), set HYPEQUERY_SKIP_INSTALL=1 and install the packages yourself.

The generated scaffold is written for modern ESM and NodeNext-style resolution, so local relative imports include the .js extension where needed.

Use init when you want the CLI to create the starting files for you. If those files already exist and you only need to refresh schema.ts, use generate instead.

Example:

# Interactive mode (recommended)
npx @hypequery/cli init

# Non-interactive with custom path
npx @hypequery/cli init --path src/analytics --no-interactive

# Scaffold the datasets semantic API for specific tables
npx @hypequery/cli init --style datasets --tables users,orders

# Scaffold datasets for every table, with context-based auth helpers
npx @hypequery/cli init --style datasets --all-tables --auth context

Interactive mode first asks whether to use a ClickHouse server/Cloud or embedded chDB. It then asks for the selected driver's connection or storage details, the output directory, API style, and authentication scaffold. If the ClickHouse URL is left blank, the remaining credential questions are skipped and placeholder configuration is generated. Run the command from the project directory containing package.json; otherwise the CLI asks for confirmation before it writes any files.

hypequery dev [file]

# Without installation
npx @hypequery/cli dev [path/to/queries.ts] [options]

# With installation
npx hypequery dev [path/to/queries.ts] [options]

Options:

• [file] – Optional path to your entry file. When omitted, the CLI searches, in order: hypequery.ts, analytics/api.ts, src/analytics/api.ts, api.ts, src/api.ts, analytics/queries.ts, src/analytics/queries.ts, queries.ts, src/queries.ts
• --path <path> – Analytics directory to load from (resolves <path>/api.ts, falling back to <path>/queries.ts)
• -p, --port <port> – Desired port (default: 4000)
• -h, --hostname <host> – Bind address (default: localhost)
• --no-watch – Run once without watching for file changes
• --open – Open the local server URL in your default browser after the server starts
• -q, --quiet – Reduce startup noise

What it does:

The dev server:

• Loads your ClickHouse schema to display table counts
• Registers all queries from your queries file
• Starts a local HTTP server for your queries
• Provides interactive API documentation at /docs
• Auto-reloads on file changes (unless --no-watch)
• Displays query execution stats

When --open is set, the CLI opens your browser to the local server URL.

Example:

# Basic usage
npx @hypequery/cli dev

# Custom port with browser auto-open
npx @hypequery/cli dev --port 3000 --open

# Run once without file watching
npx @hypequery/cli dev --no-watch

TypeScript files:

Point the command at your TypeScript entry point (for example analytics/queries.ts) and the CLI loads it via the embedded runtime. No separate tsx install is necessary.

hypequery generate

# Without installation
npx @hypequery/cli generate [options]

# With installation
npx hypequery generate [options]

hypequery generate auto-detects remote ClickHouse configuration and ships with that driver, so the remote path needs no extra database package. Pass --database chdb to introspect an embedded ClickHouse session instead; this requires chdb, which init --database chdb installs automatically. Add --chdb-path <dir> for a persistent session. If the CLI detects a chDB dependency without an explicit driver, it stops with the exact command to run rather than silently opening an empty in-memory session.

Detection prefers remote ClickHouse configuration over an installed chdb dependency. The order is: CLICKHOUSE_* environment variables, ClickHouse variables in .env, then a chdb dependency. If none are present, generation stops and asks you to select a database explicitly. Use --database clickhouse or --database chdb to override detection. This means a project may depend on chdb and still generate against ClickHouse Cloud:

CLICKHOUSE_URL=https://example.clickhouse.cloud:8443 \
CLICKHOUSE_DATABASE=default \
CLICKHOUSE_USERNAME=default \
CLICKHOUSE_PASSWORD=secret \
npx hypequery generate --database clickhouse

This is the command most users want after initial setup. Run it whenever your ClickHouse schema changes and you need to refresh the generated TypeScript types.

Options:

• -o, --output <file> – Where to write the generated types. When omitted, the CLI reuses an existing schema file (searching analytics/schema.ts, src/analytics/schema.ts, schema.ts, src/schema.ts) and otherwise defaults to analytics/schema.ts
• --path <dir> – Analytics directory to write into (derives <dir>/schema.ts). Takes effect when --output is not set
• --tables <names> – Comma-separated list of tables to include. By default all ClickHouse tables are introspected
• --database <type> – Override the detected database driver: clickhouse or chdb
• --chdb-path <path> – With --database chdb, select the embedded session directory to introspect; omit only when intentionally generating against a new in-memory session

hypequery generate:types is an alias for hypequery generate and accepts the same options.

What it does:

The generator:

• Connects to remote ClickHouse using CLICKHOUSE_*, or opens the configured chDB session
• Introspects your database schema
• Generates TypeScript interfaces for all tables
• Updates your schema file with type-safe definitions

For remote ClickHouse, ensure the CLICKHOUSE_* variables are set (or run hypequery init first). For chDB, use an on-disk session path when the schema was created by another process; an in-memory session starts empty in each CLI invocation.

Unlike init, generate does not scaffold client.ts or queries.ts. It only updates the generated schema types.

Example:

# Generate all tables
npx @hypequery/cli generate

# Generate specific tables only
npx @hypequery/cli generate --tables users,events

hypequery generate:datasets

# Without installation
npx @hypequery/cli generate:datasets [options]

# With installation
npx hypequery generate:datasets [options]

Scaffolds dataset (semantic layer) definitions from a remote ClickHouse schema, so you don't have to hand-write dimensions and measures for every table. This standalone command currently uses CLICKHOUSE_* configuration. For chDB, hypequery init --database chdb --style datasets can generate dataset definitions during the initial scaffold, but generate:datasets does not currently accept the chDB driver or session path.

Options:

• -o, --output <file> – Where to write the generated datasets. Defaults to analytics/datasets.ts, alongside hypequery generate's analytics/schema.ts
• --path <dir> – Analytics directory to write into (derives <dir>/datasets.ts). Takes effect when --output is not set
• --tables <names> – Comma-separated list of tables to include. By default all tables are scaffolded
• --exclude-tables <names> – Comma-separated list of tables to exclude
• --tenant-column <column> – Set tenantKey to this column on every table that has it. Only pass this once a trusted runtime tenant scope is configured
• --force – Atomically replace an existing output file when generated contents differ
• --check – Do not write; exit non-zero when the output file is missing or out of date
• --diff – Do not write; print the generated changes and exit non-zero when they differ

What it does:

The generator connects to ClickHouse with your CLICKHOUSE_* env vars and renders a datasets export containing a dataset(...) definition per table with inferred dimensions and measures. It creates a missing output file, but refuses to overwrite an existing customized file unless you pass --force. Without --force the output is created exclusively, so a file another process wrote in the meantime is refused rather than clobbered; with --force the replacement is atomic and keeps the existing file's permissions. Use --check in CI or --diff to review schema-driven changes without writing. Review and customize the output, then import it into your application or api.ts.

Column names such as tenant_id, organization_id, or customer_id are reported as possible tenant-key candidates — all of them, not just the first match — but the generator never enables tenantKey from a name match. Tenant isolation is a security policy: add it explicitly only after configuring trusted runtime tenant scope in your application or Serve API.

To turn isolation on, pass --tenant-column <column>: every table that has that column gets a matching tenantKey, and tables that don't are reported as warnings. hypequery init --auth context does this for you, scaffolding an api.ts with a trusted tenant runtime on tenant_id and generating datasets with tenantKey: 'tenant_id'.

Regeneration replaces the whole file, so pass --tenant-column again on every refresh of a tenant-scoped project. Without it the new file has no tenantKey and tenant-scoped requests fail until you restore it. init prints the exact command to reuse.

Example:

# Generate datasets for all tables (writes analytics/datasets.ts)
npx @hypequery/cli generate:datasets

# Generate into your analytics folder for specific tables
npx @hypequery/cli generate:datasets --path analytics --tables users,orders

# Review regeneration without overwriting customizations
npx @hypequery/cli generate:datasets --path analytics --diff

# Verify generated definitions in CI
npx @hypequery/cli generate:datasets --path analytics --check

hypequery generate:manifest <api>

npx hypequery generate:manifest analytics/api.ts --output analytics/hypequery-manifest.json

Loads the API module, calls api.manifest(), and writes the result as JSON: each query, metric and dataset key (dataset:<name> for datasets) mapped to its HTTP method and full path. Import the file in the module that creates your React hooks, together with import type { api } and InferApiType, so no server code reaches the browser bundle. See React: setup.

The module must export the value returned by createAPI() or initServe(...).serve(...). Loading it runs its top-level code, so the environment it needs to construct a client must be available.

Options:

• -o, --output <file> – Where to write the manifest. Defaults to analytics/hypequery-manifest.json. An existing file is overwritten

Re-run it whenever you add or re-route an endpoint, for example in a prebuild script.

hypequery generate:client [contract]

# From a client contract exported by a Python API
npx hypequery generate:client client-contract.json --output src/hypequery-client.ts

# From the live cloud release of the target chosen with `hypequery login`
npx hypequery generate:client --cloud --output src/hypequery-client.ts

Generates a browser-safe TypeScript file from a client contract: the signed description of each endpoint's fields, routes and schema hash. It exports ClientApi (request and response types for createAnalyticsHooks<ClientApi>()), clientManifest (routes and schema hashes), clientContractHash, and, with --cloud, clientBaseUrl. The generator reads data only: it never imports your API module or opens a database connection.

Contracts come from a Python API (python -m hypequery export client-contract, see Python: React and MCP clients) or from a cloud release. Only the build view is accepted; the authorized view served at a live /v1/client-contract route is refused. A TypeScript API does not export a client contract: type its hooks with InferApiType and generate:manifest instead.

Options:

• -o, --output <file> – Where to write the client. Defaults to analytics/hypequery-client.ts
• --check – Do not write; exit non-zero when the output is missing or out of date
• --force – Replace an existing generated file. Files not written by generate:client are never overwritten
• --cloud – Read the contract from the live cloud release instead of a file
• --project <project>, --environment <environment> – With --cloud, override the target chosen at login
• --endpoint <url> – With --cloud, an HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN

When an endpoint changes after the client was generated, the server answers requests from the old client with 409 CLIENT_SCHEMA_CHANGED, and the hooks raise ClientSchemaChangedError. Regenerate the client and review the type errors.

hypequery deploy <cloud>

Builds the publication module, prepares a release for the logged-in target, and submits it. Once Cloud accepts the release, the CLI prints where it's served:

Hosted endpoints
  REST  https://<environment-slug>.hypequery.app
    orders  POST https://<environment-slug>.hypequery.app/api/analytics/datasets/orders/query
  MCP   https://<environment-slug>.hypequery.app/mcp

Cloud provides these URLs, so the CLI follows Cloud's current routing. A live release is required before dataset calls work. A Cloud release that doesn't provide endpoint details leaves deploy output unchanged.

The build refuses a derived measure the deployment contract cannot carry (one that references another derived measure, or uses a literal anywhere other than round decimals or a coalesce fallback) with an error naming the dataset and measure, for example orders.doubled: a numeric literal cannot be an arithmetic operand in a deployable formula. See Deployable formulas.

Named code drafts

npx hypequery deploy analytics/cloud.ts --draft revenue-update
# A prebuilt bundle supports the same option:
npx hypequery deployment:submit analytics/hypequery-deployment --release analytics/hypequery-deployment.release.json --draft revenue-update

Use lowercase letters, numbers and single hyphens, up to 64 characters. Reusing that name updates the same draft in the target project. The CLI prints its draft ID and staging endpoint, then stops; it does not print Production connection configuration or change the active release. --draft cannot be combined with --replace-restored.

Review and test the saved model in Cloud before publishing it. Uploading again does not silently advance a stale draft's Production base. If Production has changed, incorporate those changes in your repository, upload to the same draft, and explicitly refresh its base in Cloud before reviewing publication again. This option requires a Cloud service that supports named code draft uploads.

hypequery deployment:status

Shows the current release and Cloud-provided REST and MCP URLs without building or deploying again. It uses the target and deployment credential saved by hypequery login. With an explicit deployment credential, pass both --project and --environment.

npx hypequery deployment:status
npx hypequery deployment:status --mcp-config

The command says when no release is live. Its optional MCP configuration uses ${HYPEQUERY_API_KEY} as a placeholder and never includes the stored deployment credential.

hypequery mcp [file]

Serves the project's datasets over stdio for a local MCP client.

Without [file], the command looks for a Serve API file in the current directory: hypequery.ts, analytics/api.ts, src/analytics/api.ts, api.ts, src/api.ts, analytics/queries.ts, or src/analytics/queries.ts. It serves the datasets registered with serve({ queryBuilder, datasets }) in that file. With an absolute [file] it runs from any directory: the file's imports resolve from its own project, and that project's .env* files are loaded (values already set in the environment win). See MCP for client setup.

Supply HYPEQUERY_API_KEY through your environment or secret manager before running the check; the command never takes the key as an argument.

npx hypequery mcp --self-test --url https://<environment-slug>.hypequery.app/mcp

hypequery skill install

Writes hypequery's agent skills where coding agents load them, so Claude Code, Cursor and Codex know how to author datasets and query them without guessing the API:

• hypequery-datasets: defining datasets, measures, tenancy and relationships in TypeScript or Python.
• hypequery-query: answering questions through the MCP tools or HTTP endpoints instead of writing SQL.

npx hypequery skill install

Re-running is safe: up-to-date skills are left alone, and an edited skill is never replaced without --force. The Python CLI has the same command: hypequery skill install.

Environment variables

These variables are read whenever the CLI talks to a remote ClickHouse server (either during init in non-interactive mode or during later remote-driver commands). They are not used by chDB:

Set these in an env file (the default ClickHouse init flow will scaffold .env for you) or export them in CI/CD before running remote-driver CLI commands.

The CLI reads the same cascade Next.js and Vite use, most specific first:

1. .env.$NODE_ENV.local
2. .env.local
3. .env.$NODE_ENV
4. .env

Earlier files win, and a variable already present in the real environment beats every file. So a Next.js project that keeps its ClickHouse credentials in .env.local works with the CLI without duplicating them into .env.

Troubleshooting

Connection errors

Verify the environment variables above and ensure network access to ClickHouse. The CLI reports detailed errors with actionable hints:

• ECONNREFUSED – ClickHouse is not running or the URL/port is wrong
• Authentication failed – Check username and password
• TLS errors – Verify SSL configuration

Missing files

Run hypequery init --force to regenerate the analytics/ folder if it was removed.

TypeScript errors

If you see "Unexpected token" or syntax errors when running hypequery dev, the usual causes are:

1. A broken import path
2. A missing dependency in your project
3. A tsconfig.json mismatch affecting module resolution

As a fallback, compile your TypeScript first:

tsc src/analytics/queries.ts
npx @hypequery/cli dev src/analytics/queries.js

Wrong file or export

If the CLI reports that your file doesn't export an API properly:

1. Ensure your entry file exports the hypequery API as api (a default export also works)
2. Check the error message for the list of exports found
3. See the expected format in the error message

The CLI accepts either entry style. Query-builder routes use serve({ queries }):

import { initServe } from '@hypequery/serve';

const { query, serve } = initServe({
  context: () => ({ db }),
});

const myQuery = query({
  query: async ({ ctx }) => {
      // ...
    },
});

export const api = serve({
  queries: { myQuery },
});

The datasets semantic API uses createAPI:

import { createAPI } from '@hypequery/serve';
import { db } from './client.js';
import { datasets } from './datasets.js';

export const api = createAPI({
  queryBuilder: db,
  datasets,
});