CLI Reference

Complete reference for the SQG command-line interface.

Output Modes

SQG has three output modes:

Mode	Flag	Behavior
Default	(none)	Spinner progress, timing, and summary
Verbose	`--verbose`	Per-query detail with debug information
JSON	`--format json`	Machine-readable JSON, no visual output

Default output:

✔ Introspected 5 queries (0.4s)
✔ Generated 2 files from queries.sql (1.2s)

  -> generated/Queries.java    (5 queries, 2 enums)
  -> generated/queries.ts      (5 queries)

Done in 1.8s

Verbose output (--verbose):

  Executing query: list_users
  + list_users
  Executing query: get_user_by_id
  + get_user_by_id
  ...

Commands

`sqg <config-file>`

Generate code from a configuration file.

sqg sqg.yaml
sqg path/to/config.yaml

Options:

Option	Description
`--validate`	Validate configuration without generating code
`--format <format>`	Output format: `text` (default) or `json`
`--verbose`	Enable verbose logging (per-query detail)

Examples:

# Generate code
sqg sqg.yaml

# Validate only
sqg --validate sqg.yaml

# JSON output for tooling
sqg --format json sqg.yaml

# Verbose mode (per-query detail)
sqg --verbose sqg.yaml

# Combine options
sqg --validate --format json sqg.yaml

`sqg init`

Initialize a new SQG project with example files.

sqg init [options]

When run without --generator in an interactive terminal, sqg init launches an interactive wizard that walks you through project setup:

┌  Create a new SQG project
│
◆  Project name
│  my-project
│
◆  Generator
│  ● typescript/sqlite
│  ○ typescript/duckdb
│  ○ java/sqlite
│  ○ java/duckdb
│  ○ java/postgres
│
◆  Output directory
│  ./generated
│
◇  Files to create:
│    sqg.yaml      Project configuration
│    queries.sql   Example SQL queries
│    ./generated/  Output directory
│
◆  Create files?
│  Yes
│
└  Done! Run: sqg sqg.yaml

When --generator is passed, the command runs non-interactively (useful for scripts and CI).

Options:

Option	Default	Description
`-t, --generator <generator>`	(interactive)	Code generation generator. Omit for interactive mode
`-o, --output <dir>`	`./generated`	Output directory for generated files
`-f, --force`	`false`	Overwrite existing files

Examples:

# Interactive wizard (recommended for first-time setup)
sqg init

# Non-interactive: TypeScript + SQLite
sqg init --generator typescript/sqlite

# Non-interactive: TypeScript + DuckDB project
sqg init --generator typescript/duckdb

# Java + SQLite project
sqg init --generator java/sqlite

# Java + DuckDB with Arrow API
sqg init --generator java/duckdb/arrow

# Custom output directory
sqg init --output ./src/db

# Overwrite existing files
sqg init --force

# Full example
sqg init --generator typescript/duckdb --output ./src/generated --force

Created files:

./
├── sqg.yaml        # Project configuration
├── queries.sql     # Example SQL file with migrations and queries
└── generated/      # Output directory (empty)

`sqg syntax`

Display SQL annotation syntax reference.

sqg syntax

Shows:

Query types (MIGRATE, QUERY, EXEC, TESTDATA)
Modifiers (:one, :pluck, :all)
Variable syntax (@set, ${var})
Examples

`sqg mcp`

Start MCP (Model Context Protocol) server for AI assistants.

sqg mcp

The MCP server runs on stdio and provides AI assistants (like Claude Desktop and Cursor) with access to SQG’s code generation capabilities.

Available tools:

generate_code - Generate type-safe code from SQL queries
validate_sql - Validate SQL queries with SQG annotations

Example configuration for Claude Desktop:

{
  "mcpServers": {
    "sqg": {
      "command": "sqg",
      "args": ["mcp"]
    }
  }
}

See the Build with AI guide for detailed setup instructions.

Global Options

These options work with all commands:

Option	Description
`-v, --version`	Display version number
`-h, --help`	Display help with ASCII branding
`--verbose`	Enable verbose logging
`--format <format>`	Output format: `text` or `json`

JSON Output Mode

Use --format json for machine-readable output, ideal for:

CI/CD pipelines
Editor integrations
AI assistants
Build tools

All visual output (spinners, progress, summary) is suppressed in JSON mode.

Successful Generation

sqg --format json sqg.yaml

{
  "status": "success",
  "generatedFiles": [
    "/path/to/generated/my-app.ts"
  ]
}

Validation Result

sqg --validate --format json sqg.yaml

{
  "valid": true,
  "project": {
    "name": "my-app",
    "version": 1
  },
  "sqlFiles": ["queries.sql"],
  "generators": ["typescript/sqlite"]
}

Error Output

sqg --format json invalid.yaml

{
  "status": "error",
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "SQL file not found: queries.sql",
    "suggestion": "Check that queries.sql exists relative to /path/to/project",
    "context": {
      "file": "/path/to/project/queries.sql"
    }
  }
}

Text mode errors are displayed with formatting:

 ERROR  SQL file not found: queries.sql

   Suggestion: Check that queries.sql exists relative to /path/to/project

Error Codes

SQG provides structured error codes for programmatic handling:

Code	Description
`CONFIG_PARSE_ERROR`	Invalid YAML syntax in config file
`CONFIG_VALIDATION_ERROR`	Configuration doesn’t match schema
`FILE_NOT_FOUND`	SQL or config file doesn’t exist
`INVALID_GENERATOR`	Unknown or invalid generator
`SQL_PARSE_ERROR`	Invalid SQL annotation syntax
`SQL_EXECUTION_ERROR`	Query failed during type introspection
`DUPLICATE_QUERY`	Two queries have the same name
`MISSING_VARIABLE`	Variable referenced but not defined with `@set`
`VALIDATION_ERROR`	General validation error
`DATABASE_ERROR`	Database connection or execution error
`TYPE_MAPPING_ERROR`	Unable to map SQL type to generator language

Error Suggestions

All errors include actionable suggestions:

{
  "error": {
    "code": "INVALID_GENERATOR",
    "message": "Invalid generator 'typescript/mysql'",
    "suggestion": "Valid generators: typescript/sqlite, typescript/duckdb, java/sqlite, java/duckdb, java/postgres"
  }
}

Exit Codes

Code	Meaning
`0`	Success
`1`	Error (check output for details)

Environment Variables

Variable	Description
`SQG_POSTGRES_URL`	PostgreSQL connection string for type introspection

Example:

export SQG_POSTGRES_URL="postgresql://user:pass@localhost:5432/mydb"
sqg sqg.yaml

Configuration File

See Getting Started for full configuration documentation.

Minimal example:

version: 1
name: my-app

sql:
  - files:
      - queries.sql
    gen:
      - generator: typescript/sqlite
        output: ./src/generated/

Supported Generators

Generators follow the format <language>/<engine>[/<driver>]:

Generator	Engine	Description
`typescript/sqlite`	SQLite	TypeScript with better-sqlite3 (default driver)
`typescript/duckdb`	DuckDB	TypeScript with @duckdb/node-api (default driver)
`java/sqlite`	SQLite	Java with JDBC (default driver)
`java/duckdb`	DuckDB	Java with JDBC (default driver)
`java/duckdb/arrow`	DuckDB	Java with DuckDB Arrow API
`java/postgres`	PostgreSQL	Java with JDBC (default driver)

The driver can be omitted to use the default. For example, typescript/sqlite is equivalent to typescript/sqlite/better-sqlite3.

See individual generator pages for detailed documentation:

Troubleshooting

Verbose Mode

sqg --verbose sqg.yaml

Shows:

Per-query execution detail
Database initialization status
Type introspection results
SQL parsing details

Validate Before Generate

sqg --validate sqg.yaml

Catches configuration errors before running full generation.

Check Version

sqg --version

Ensure you’re running the expected version.