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 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 src/datasets/generated.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

What it does:

The generator connects to ClickHouse with your CLICKHOUSE_* env vars, introspects the matching tables, and writes a datasets export containing a dataset(...) definition per table with inferred dimensions and measures. Review and customize the output, then import it into your application or api.ts.

Example:

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

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

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 your .env (the default ClickHouse init flow will scaffold this file for you) or export them in CI/CD before running remote-driver CLI commands.

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,
});