Scythe CLI Reference: All Commands and Flags

scythe <command> [options]

generate#

scythe generate [--config <path>] [--allow-output-escape] [--validate-output]

Flag	Default	Description
`-c, --config`	`scythe.toml`	Path to config file
`--allow-output-escape`	false	Allow a `[[sql.gen]]` `output` directory to resolve outside the project root (via `../` traversal or an absolute path)
`--validate-output`	false	Validate each target's generated output with the real compiler/linter for its language (`poly`, `tsc`, `javac`, `kotlinc`, `gofmt`, `ruby`, …)

check#

Validate SQL without generating code — parsing, analysis, and lint rules, plus provenance verification of already-generated artifacts against the current schema.

scythe check [--config <path>] [--database-url <url>] [--format <format>] [--output <path>] [--exit-zero]

Flag	Default	Description
`-c, --config`	`scythe.toml`	Path to config file
`--database-url`	none	Verify inferred types and detect schema drift against a live PostgreSQL database
`--format`	`human`	Output format: `human`, `sarif`, or `json`
`-o, --output`	stdout	Write findings to a file
`--exit-zero`	false	Exit 0 even if error-severity findings are present (advisory CI gate)

Exits with code 2 when any error-severity finding is present (unless --exit-zero), and 1 only on operational failure — an unreadable config, unparseable SQL, or an I/O error. --database-url is PostgreSQL only: type verification needs the extended query protocol's describe step, and drift detection reads pg_catalog directly through tokio-postgres.

Every generated file carries a first-line provenance header scythe checks against the current schema, queries, engine, backend, and version — see the provenance and drift rule tables in the lint rule reference.

lint#

Lint SQL files for correctness, performance, and style.

scythe lint [--config <path>] [--fix] [--dialect <dialect>] [files...]

Flag	Default	Description
`-c, --config`	`scythe.toml`	Path to config file
`--fix`	false	Auto-fix violations where possible
`--dialect`	(none)	SQL dialect for sqruff rules. Without it: with a config file, each `[[sql]]` block uses its own `engine`; with explicit files, scythe falls back to the first `[[sql]].engine`
`files...`	(from config)	SQL files to lint directly

With a config file, scythe lint runs both scythe's schema-aware rules and sqruff rules, each block using its own engine's dialect unless --dialect overrides all of them. Given explicit files instead, it runs sqruff rules only, with no schema context.

fmt#

Format SQL files using sqruff.

scythe fmt [--config <path>] [--check] [--diff] [--dialect <dialect>] [files...]

Flag	Default	Description
`-c, --config`	`scythe.toml`	Path to config file
`--check`	false	Report files needing formatting; exit 1 if any
`--diff`	false	Show a unified diff of changes
`--dialect`	(none)	SQL dialect for formatting; falls back to the first `[[sql]].engine`
`files...`	(from config)	SQL files to format directly

migrate#

Convert a sqlc project to scythe format.

scythe migrate [sqlc_config]

Argument	Default	Description
`sqlc_config`	`sqlc.yaml`	Path to sqlc config file (v1 or v2)

See Migrating from sqlc for the full before/after walkthrough.

audit#

Run security rules over SQL schema and queries.

scythe audit [OPTIONS] [files...]

Flag	Default	Description
`-c, --config`	`scythe.toml`	Path to config file
`--format`	`human`	Output format: `human`, `sarif`, `json`
`--list-rules`	false	Print the rule catalog (id, name, severity, category) and exit 0
`--explain <RULE_ID>`	–	Print the description and CWE refs for a rule, then exit 0
`--severity <LEVEL>`	–	Drop findings below this severity (`off`, `warn`, `error`)
`--exit-zero`	false	Exit 0 even if error-severity findings are present
`-o, --output <PATH>`	stdout	Write reporter output to a file
`--ignore-suppressions`	false	Disable inline `-- scythe-audit: ignore[...]` annotations
`--dialect <DIALECT>`	`postgres`	SQL dialect for explicit-file mode
`files...`	(from config)	SQL files to audit directly

Exits with code 2 on any error-severity finding (unless --exit-zero) — distinct from scythe lint's exit code 1, so CI can tell lint failures apart from security failures. Full rule catalog: Security Audit.

inspect#

Connect to a live database and run operational health checks — missing FK indexes, disabled RLS with policies, duplicate indexes.

scythe inspect [OPTIONS] [DATABASE_URL]

Flag	Default	Description
`DATABASE_URL`	(from env)	Positional connection URL; falls back to `$DATABASE_URL`, then `$SCYTHE_DATABASE_URL`
`--format`	`human`	Output format: `human`, `sarif`, `json`
`--list-checks`	false	Print the check catalog and exit 0
`--severity <LEVEL>`	–	Drop findings below this severity
`--exit-zero`	false	Exit 0 even if error-severity findings are present
`-o, --output <PATH>`	stdout	Write reporter output to a file
`--explain <CHECK_ID>`	–	Print full rationale and remediation for one check, then exit 0
`-c, --config <PATH>`	`scythe.toml`	Supplies `[inspect].database_url` when no URL is given elsewhere
`--dialect <DIALECT>`	(from URL scheme)	Engine override: `postgres`/`postgresql` (13 checks) or `mysql`/`mariadb` (4 checks)

Exit Codes#

Code	Meaning
0	Success
1	Operational failure (unreadable config, parse error, I/O error), or a `scythe lint` / `scythe fmt --check` failure
2	Error-severity finding from `scythe audit`, `scythe inspect`, or `scythe check`

Examples#

# Generate code with default config
scythe generate
 
# Check SQL validity
scythe check
 
# Lint with auto-fix
scythe lint --fix
 
# Format check in CI
scythe fmt --check
 
# Migrate from sqlc
scythe migrate sqlc.yaml
 
# List every audit rule
scythe audit --list-rules
 
# CI: emit SARIF for GitHub code scanning
scythe audit --format sarif -o audit.sarif
 
# Advisory mode (don't fail the build)
scythe audit --exit-zero

Configuration — every scythe.toml field these commands read.
Linting and Security Audit — the rule catalogs behind lint and audit.

Updated Aug 15, 2026