CLI reference

The hypequery CLI provides commands for scaffolding, generating types, and running development servers. Every command expects access to your ClickHouse credentials via the prompts presented during init or via the CLICKHOUSE_* environment variables listed below.

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 ships with an embedded TypeScript runtime (powered by tsx). Point it at your .ts or .tsx queries file and the CLI transpiles it in-process—no extra dependencies, watchers, or custom launch commands required. If you already compile to JavaScript, you can still target the generated .js file instead.

Commands at a glance

Command	Purpose
`hypequery init`	Scaffold the `analytics/` folder, collect ClickHouse credentials, and optionally create an example query
`hypequery dev [queries-file]`	Run the local dev server backed by `@hypequery/serve` with hot reload
`hypequery generate`	Rebuild `analytics/schema.ts` (optionally watching for remote schema changes)

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:

--database <type> – Database type (currently only clickhouse)
--path <dir> – Target directory for client.ts, schema.ts, and queries.ts. Defaults to analytics/
--no-example – Skip generating the sample query
--no-interactive – Skip prompts and read the ClickHouse host/database/user/password from CLICKHOUSE_* env vars. The command fails if any required variable is missing
--force – Overwrite existing files without asking

What it does:

During the flow the CLI tests your ClickHouse connection immediately using the credentials you provide. On success it:

Writes .env with your connection details
Generates client.ts, schema.ts, and queries.ts in the selected directory
Creates or updates .gitignore to protect secrets
Prints follow-up instructions for hypequery dev

Example:

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

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

`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 queries.ts. Defaults to analytics/queries.ts, src/analytics/queries.ts, or the nearest hypequery.ts
-p, --port <port> – Desired port (default: 4000)
-h, --hostname <host> – Bind address (default: localhost)
--no-watch – Run once without watching for file changes
--cache <provider> – Cache provider (memory | redis | none)
--redis-url <url> – Connection string when using the Redis cache provider
--open – Open the generated Docs URL in your default browser after the server starts
--cors – Enable CORS support in the dev server
-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 docs page.

Example:

# Basic usage
npx @hypequery/cli dev

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

# Disable caching for debugging
npx @hypequery/cli dev --cache none

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 serve [file]`

npx @hypequery/cli serve src/analytics/queries.ts --port 4000

Starts a production-ready HTTP server without file watching (ideal for Docker/PM2). Accepts the same flags as dev (port, hostname, cache options). Use this command in containers or long-running processes when you don’t need auto-reload.

`hypequery generate`

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

# With installation
npx hypequery generate [options]

hypequery generate auto-detects your database configuration (currently ClickHouse) and ships with the necessary driver, so there’s no extra package to install. Use --database <type> once additional drivers become available or you want to override detection.

Options:

--output <file> – Where to write the generated types. Defaults to your existing analytics/schema.ts or analytics/schema.ts if not found
--tables <names> – Comma-separated list of tables to include. By default all ClickHouse tables are introspected
--database <type> – Override the detected database driver (currently only clickhouse)

What it does:

The generator:

Connects to ClickHouse using your CLICKHOUSE_* env variables
Introspects your database schema
Generates TypeScript interfaces for all tables
Updates your schema file with type-safe definitions

The generator shares the CLICKHOUSE_* configuration with the rest of the CLI, so ensure those env vars are set (or run hypequery init first).

Example:

# Generate all tables
npx @hypequery/cli generate

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

Environment variables

These variables are read whenever the CLI talks to ClickHouse (either during init in non-interactive mode or during later commands):

Variable	Description
`CLICKHOUSE_HOST`	Fully-qualified host URL, e.g. `https://example.clickhouse.cloud:8443`
`CLICKHOUSE_DATABASE`	Database to target (defaults to `default`)
`CLICKHOUSE_USERNAME`	Username used for CLI connections
`CLICKHOUSE_PASSWORD`	Password or token
`CLICKHOUSE_URL` / `CLICKHOUSE_USER` / `CLICKHOUSE_PASS`	Legacy aliases also detected by the CLI

Set these in your .env (the init command will scaffold this file for you) or export them in CI/CD before running 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 wrong host/port
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:

Make sure tsx is installed:
```
npm install -D tsx
```
The CLI will automatically restart with TypeScript support

Alternatively, 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:

Ensure your queries file exports an api variable from initServe or defineServe
Check the error message for the list of exports found
See the expected format in the error message

Example of correct format:

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

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

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

CLI reference

Installation

TypeScript support

Commands at a glance

hypequery init

hypequery dev [file]

hypequery serve [file]

hypequery generate

Environment variables

Troubleshooting

Connection errors

Missing files

TypeScript errors

Wrong file or export

On this page

`hypequery init`

`hypequery dev [file]`

`hypequery serve [file]`

`hypequery generate`