CLI Reference

The sqldoc CLI provides commands for code generation, validation, linting, schema management, and migrations.

Installation

Homebrew

brew install elliots/sqldoc/sqldoc

or download the latest release from GitHub Releases for your platform.

bash

sqldoc init

sqldoc compile

Compile SQL files and output merged SQL with generated statements

sqldoc compile [path] [options]

Arguments:

Name	Required	Description
path	No	Path to SQL files or directory (defaults to config schema)

Options:

Flag	Description
-c, --config <path>	Path to sqldoc.config.ts
-o, --output <path>	Write to file instead of stdout
--project <name>	Select a named project from multi-project config

---

sqldoc codegen

Run code generation plugins (templates, docs, etc.)

sqldoc codegen [path] [options]

Arguments:

Name	Required	Description
path	No	Path to SQL files or directory (defaults to config schema)

Options:

Flag	Description
-c, --config <path>	Path to sqldoc.config.ts
-p, --plugins <names>	Comma-separated project-level plugin names to run (default: all)
-t, --template <names>	Run template(s) by slug (comma-separated), ignoring config (output to stdout or -o dir)
-o, --output <path>	Output file path (used with --template)
--project <name>	Select a named project from multi-project config

---

sqldoc validate

Validate tags in SQL files

sqldoc validate [path] [options]

Arguments:

Name	Required	Description
path	No	Path to SQL files or directory (defaults to config schema)

Options:

Flag	Description
-c, --config <path>	Path to sqldoc.config.ts
--project <name>	Select a named project from multi-project config

---

sqldoc lint

Run lint rules from namespace plugins against SQL files

sqldoc lint [path] [options]

Arguments:

Name	Required	Description
path	No	Path to SQL files or directory (defaults to config schema)

Options:

Flag	Description
-c, --config <path>	Path to sqldoc.config.ts
-v, --verbose	Show ignored rules
--project <name>	Select a named project from multi-project config

---

sqldoc schema

Schema inspection and comparison

sqldoc schema [options]

sqldoc schema inspect

Inspect schema from SQL files, directory, or database

sqldoc schema inspect [source] [options]

Arguments:

Name	Required	Description
source	No	SQL file, directory, or database URL (defaults to config schema)

Options:

Flag	Description
-c, --config <path>	Path to sqldoc.config.ts
-f, --format <format>	Output format: sql, json
--dev-url <url>	Dev database URL (pglite, docker://<image>, dockerfile://<path>, postgres://...)
--project <name>	Select a named project from multi-project config

sqldoc schema diff

Compare two schema states

sqldoc schema diff [options]

Options:

Flag	Description
--from <source>	Source state: SQL file, directory, or database URL (default: empty)
--to <source>	Target state: SQL file, directory, or database URL
-c, --config <path>	Path to sqldoc.config.ts
-f, --format <format>	Output format: sql, json, pretty
--dev-url <url>	Dev database URL (pglite, docker://<image>, dockerfile://<path>, postgres://...)
--check	Exit non-zero if schemas differ (CI mode)
--project <name>	Select a named project from multi-project config

---

sqldoc migrate

Generate migration files or check for schema drift

sqldoc migrate [options]

Options:

Flag	Description
-c, --config <path>	Path to sqldoc.config.ts
--project <name>	Select a named project from multi-project config
--check	Exit non-zero if schema differs from migrations (CI mode)
--name <name>	Custom migration name
--force	Allow destructive changes (DROP TABLE, DROP COLUMN, etc.)

---

sqldoc doctor

Check project setup and report status

sqldoc doctor [options]