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.

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:

• --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 URL/database/user/password from CLICKHOUSE_* env vars. The command fails if any required variable is missing
• --force – Overwrite existing files without asking
• --skip-connection – Skip the initial ClickHouse connectivity test and scaffold files without validating the connection first

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
• Installs the scaffold dependencies the generated files expect
• Prints follow-up instructions for hypequery dev

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

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

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:

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

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

Environment variables

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

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 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 queries file exports an api variable created from serve({ queries })
2. Check the error message for the list of exports found
3. See the expected format in the error message

Example of correct format:

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

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

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

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