Tooling

CLI Commands

@gntrees/sql-builder-cli ships with focused commands to speed up query migration and schema generation.

Why Use CLI

Faster onboarding

Convert existing SQL into builder code instead of rewriting by hand.

Typed schema

Generate schema objects directly from your database for stronger autocomplete and safer queries.

Repeatable workflow

Run the same command in CI or local scripts whenever schema or SQL changes.

Install

npm install -D @gntrees/sql-builder-cli
pnpm add -D @gntrees/sql-builder-cli
yarn add -D @gntrees/sql-builder-cli

npm install -D @gntrees/sql-builder-cli
pnpm add -D @gntrees/sql-builder-cli
yarn add -D @gntrees/sql-builder-cli

Command Map

The CLI currently provides two core commands plus help output.

Command	Purpose	Key Flags
convert	Convert raw SQL string into SQL Builder code.	`--sql`, `--sqlSchema`, `--dbSchema`, `--simplify-literal`, `--output`
generate	Generate typed DB schema file from a Postgres connection URL.	`--url`, `--output`
help	Print usage information and command syntax.	`--help`, `-h`, `help`

npx @gntrees/sql-builder-cli --help
npx @gntrees/sql-builder-cli help

npx @gntrees/sql-builder-cli --help
npx @gntrees/sql-builder-cli help

convert Command

Use convert when you already have SQL and want a fast jump to SQL Builder syntax.

Required: --sql

Optional: --sqlSchema,--dbSchema, --simplify-literal,--output

Without --output, generated code is printed to stdout.

npx @gntrees/sql-builder-cli convert   --sql="SELECT id, email FROM users WHERE is_active = true"   --sqlSchema=true   --dbSchema=true   --simplify-literal=true   --output="./src/queries/get-active-users.ts"

npx @gntrees/sql-builder-cli convert   --sql="SELECT id, email FROM users WHERE is_active = true"   --sqlSchema=true   --dbSchema=true   --simplify-literal=true   --output="./src/queries/get-active-users.ts"

generate Command

Use generate to introspect your database and create typed schema exports for DB Schema workflow.

Required: --url

Optional: --output

If no output path is provided, CLI uses its default output strategy from the generator.

npx @gntrees/sql-builder-cli generate   --url="postgres://user:password@localhost:5432/app_db"   --output="./src/db/app-db.schema.ts"

npx @gntrees/sql-builder-cli generate   --url="postgres://user:password@localhost:5432/app_db"   --output="./src/db/app-db.schema.ts"

Recipes

Two common outcomes after running CLI commands.

Output from convert

// generated from convert
import { sqlBuilder } from "@gntrees/sql-builder/pg"

const q = sqlBuilder().setFormatParamHandler("pg")

export const getActiveUsers = q
  .select(q.c("users.id"), q.c("users.email"))
  .from(q.t("users"))
  .where(q.eq(q.c("users.is_active"), q.v(true)))

// generated from convert
import { sqlBuilder } from "@gntrees/sql-builder/pg"

const q = sqlBuilder().setFormatParamHandler("pg")

export const getActiveUsers = q
  .select(q.c("users.id"), q.c("users.email"))
  .from(q.t("users"))
  .where(q.eq(q.c("users.is_active"), q.v(true)))

Output from generate

// generated from generate
import { account, user } from "./app-db.schema"
import { sqlBuilder } from "@gntrees/sql-builder/pg"

const q = sqlBuilder().setFormatParamHandler("pg")

const query = q
  .select(account.id, user.email)
  .from(account)
  .join(user)
  .on(q.eq(account.userId, user.id))

// generated from generate
import { account, user } from "./app-db.schema"
import { sqlBuilder } from "@gntrees/sql-builder/pg"

const q = sqlBuilder().setFormatParamHandler("pg")

const query = q
  .select(account.id, user.email)
  .from(account)
  .join(user)
  .on(q.eq(account.userId, user.id))