CLI Reference

Complete reference for the SQG command-line interface.

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 debug logging

Examples:

# Generate code
sqg sqg.yaml

# Validate only
sqg --validate sqg.yaml

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

# Debug mode
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]

Options:

Option	Default	Description
`-t, --generator <generator>`	`typescript/sqlite`	Code generation generator
`-o, --output <dir>`	`./generated`	Output directory for generated files
`-f, --force`	`false`	Overwrite existing files

Examples:

# TypeScript + SQLite (default)
sqg init

# 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 for command
`--verbose`	Enable debug 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

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"],
  "targets": ["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"
    }
  }
}

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_TARGET",
    "message": "Invalid generator 'typescript/mysql'",
    "suggestion": "Valid targets: 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

Debug Mode

sqg --verbose sqg.yaml

Shows:

SQL file parsing details
Database initialization
Query execution
Type introspection results

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.