supatool 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # Supatool
 
-**The AI-Native Schema Management CLI for Supabase.** Extract database schemas into LLM-friendly structures, generate `llms.txt` catalogs, and manage seeds without drowning your AI's context.
+**Schema Management CLI for PostgreSQL.** Works with Cloud SQL, Supabase, and any PostgreSQL database. Extract schemas into LLM-friendly structures, deploy diffs, apply migrations, and export seeds.
 
 [![npm version](https://img.shields.io/npm/v/supatool.svg)](https://www.npmjs.com/package/supatool)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -9,10 +9,23 @@
 
 Modern AI coding tools (Cursor, Claude, MCP) often struggle with large database schemas. Typical issues include:
 - **Token Waste:** Reading the entire schema at once consumes 10k+ tokens.
-- **Lost Context:** Frequent API calls to fetch table details via MCP lead to fragmented reasoning.
+- **Lost Context:** Frequent API calls to fetch table details lead to fragmented reasoning.
 - **Inaccuracy:** AI misses RLS policies or complex FK relations split across multiple files.
 
-**Supatool solves this** by reorganizing your Supabase schema into a highly searchable, indexed, and modular structure that helps AI "understand" your DB with minimal tokens.
+**Supatool solves this** by reorganizing your schema into a highly searchable, indexed, and modular structure that helps AI "understand" your DB with minimal tokens.
+
+---
+
+## Supported Databases
+
+Any **PostgreSQL** database:
+
+- Google Cloud SQL (PostgreSQL)
+- Supabase
+- Amazon RDS (PostgreSQL)
+- Self-hosted PostgreSQL
+
+Connection strings in both `postgresql://` and `postgres://` formats are accepted.
 
 ---
 
@@ -21,9 +34,9 @@ Modern AI coding tools (Cursor, Claude, MCP) often struggle with large database
 - **Extract (AI-Optimized)** – DDL, RLS, and Triggers are bundled into **one file per table**. AI gets the full picture of a table by opening just one file.
 - **llms.txt Catalog** – Automatically generates a standard `llms.txt` listing all OBJECTS, RELATIONS (FKs), and RPC dependencies. This serves as the "Map" for AI agents.
 - **Multi-Schema Support** – Group objects by schema (e.g., `public`, `agent`, `auth`) with proper schema-qualification in SQL.
+- **Migrate** – Apply pending `db/migrations/*.sql` files to remote, with tracking and transaction safety.
 - **Seed for AI** – Export table data as JSON. Includes a dedicated `llms.txt` for seeds so AI can see real data structures.
 - **Safe Deploy** – Push local schema changes with `--dry-run` to preview DDL before execution.
-- **CRUD (Deprecated)** – Legacy code generation is still available but discouraged in favor of LLM-native development.
 
 ---
 
@@ -31,18 +44,21 @@ Modern AI coding tools (Cursor, Claude, MCP) often struggle with large database
 
 ```bash
 npm install -g supatool
-# Set your connection string
-export SUPABASE_CONNECTION_STRING="postgresql://postgres:[password]@db.[ref].supabase.co:5432/postgres"
 
-# Extract schema and generate AI-ready docs
-supatool extract --schema public,auth -o supabase/schemas
+# Set connection string in .env.local
+echo 'DB_CONNECTION_STRING=postgresql://user:password@host:5432/dbname' > .env.local
 
+# Generate config
+supatool config:init
+
+# Extract schema and generate AI-ready docs
+supatool extract --all -o db/schemas
 ```
 
 ### Output Structure
 
 ```text
-supabase/schemas/
+db/schemas/
 ├── llms.txt          # 🗺️ THE ENTRY POINT: Read this first to understand the DB map
 ├── schema_index.json # 🤖 For JSON-parsing agents
 ├── schema_summary.md # 📄 Single-file overview for quick human/AI scanning
@@ -51,18 +67,15 @@ supabase/schemas/
     ├── tables/       # table_name.sql (DDL + RLS + Triggers)
     ├── views/
     └── rpc/
-
 ```
 
 ---
 
 ## Best Practices for AI Agents (Cursor / Claude / MCP)
 
-To get the best results from your AI coding assistant, follow these steps:
-
-1. **Start with the Map:** Always ask the AI to read `supabase/schemas/llms.txt` first.
-2. **Targeted Reading:** Once the AI identifies the relevant tables from the catalog, instruct it to open only those specific `.sql` files.
-3. **Understand Relations:** Use the `RELATIONS` section in `llms.txt` to help the AI write accurate JOINs without reading every file.
+1. **Start with the Map:** Always ask the AI to read `db/schemas/llms.txt` first.
+2. **Targeted Reading:** Once the AI identifies the relevant tables, instruct it to open only those specific `.sql` files.
+3. **Understand Relations:** Use the `RELATIONS` section in `llms.txt` to help the AI write accurate JOINs.
 4. **RPC Context:** If using functions, refer to `RPC_TABLES` in `llms.txt` to know which tables are affected.
 
 ---
@@ -71,32 +84,83 @@ To get the best results from your AI coding assistant, follow these steps:
 
 ### Extract
 
+Pull schema from remote DB into local files:
+
 ```bash
-supatool extract --all -o supabase/schemas
+supatool extract --all -o db/schemas
 # Options:
 # --schema public,agent   Specify schemas
 # -t "user_*"             Filter tables by pattern
-# --force                 Clear output dir before writing (prevents orphan files)
+# --force                 Clear output dir before writing
+```
+
+### Deploy
+
+Push local schema changes to remote (diff → migration → apply):
+
+```bash
+supatool deploy --table users --dry-run   # preview
+supatool deploy --table all --dry-run     # all tables
+supatool deploy --table users             # confirm before apply
+```
+
+### Migrate
 
+Apply pending SQL files from `db/migrations/` to remote:
+
+```bash
+supatool migrate                    # apply pending migrations
+supatool migrate --dry-run          # preview only
+supatool migrate -d path/to/dir     # custom directory
 ```
 
+Migration files are applied in alphabetical order. Applied files are tracked in a `_supatool_migrations` table (auto-created).
+
 ### Seed
 
-Export specific tables for AI reference or testing:
+Export table data as JSON for AI reference or testing:
 
 ```bash
 supatool seed --tables tables.yaml
 
+# tables.yaml format:
+# public:
+#   - users
+#   - posts
 ```
 
-*Outputs JSON files and a `llms.txt` index in `supabase/seeds/`.*
+*Outputs JSON files and a `llms.txt` index in `db/seeds/`.*
 
-### Deploy
+### Config
 
 ```bash
-supatool deploy --dry-run
+supatool config:init    # generate supatool.config.json + .env.local template
+```
+
+---
+
+## Configuration
+
+`supatool.config.json`:
+
+```json
+{
+  "schemaDir": "./db/schemas",
+  "tablePattern": "*",
+  "migration": {
+    "naming": "timestamp",
+    "dir": "db/migrations"
+  }
+}
+```
+
+`.env.local` (never commit):
 
 ```
+DB_CONNECTION_STRING=postgresql://user:password@host:5432/dbname
+```
+
+Legacy env vars are also accepted: `SUPABASE_CONNECTION_STRING`, `DATABASE_URL`.
 
 ---
 
@@ -106,4 +170,4 @@ supatool deploy --dry-run
 
 ---
 
-*Developed with ❤️ for the Supabase community. Use at your own risk. Always backup your DB before deployment.*
+*Works with any PostgreSQL database. Always backup your DB before deployment.*

package/dist/bin/helptext.js

@@ -4,49 +4,62 @@ exports.modelSchemaHelp = exports.helpText = void 0;
 // See: [src/bin/helptext.ts](./src/bin/helptext.ts) from project root
 // Help text (command section from README, English only)
 exports.helpText = `
-Supatool CLI - Supabase schema extraction and TypeScript CRUD generation
+Supatool CLI - PostgreSQL schema management (Cloud SQL, Supabase, and any PostgreSQL)
 
 Usage:
   supatool <command> [options]
 
 Commands:
-  extract            Extract database objects from Supabase
+  extract            Extract database objects from remote DB into local files
+  deploy             Deploy local schema changes to remote (diff → migration → apply)
+  migrate            Apply pending db/migrations/*.sql files to remote DB
+  seed               Export table data as AI-friendly seed JSON
+  config:init        Generate supatool.config.json and .env.local template
   gen:types          Generate TypeScript types from model YAML
-  gen:crud           Generate CRUD TypeScript code from model YAML [deprecated - prefer writing code with LLM]
   gen:docs           Generate Markdown documentation from model YAML
-  gen:sql            Generate SQL (tables, relations, RLS/security) from model YAML
-  gen:rls            Generate RLS/security SQL from model YAML
-  gen:all            Generate all outputs from model YAML
-  create             Generate a template model YAML
-  crud               Generate CRUD code from Supabase type definitions [deprecated - prefer writing code with LLM]
-  deploy             Deploy local schema changes to remote (recommended)
-  sync               Sync local and remote schemas [deprecated - use deploy]
-  seed               Export selected table data as AI-friendly seed JSON
-  config:init        Generate configuration template
-  help               Show help
+  gen:sql            Generate SQL (tables, relations, RLS) from model YAML
+  gen:rls            Generate RLS policy SQL from model YAML
+  help               Show this help
 
 Common Options:
-  -c, --connection <string>    Supabase connection string
+  -c, --connection <string>    Connection string (postgresql:// or postgres://)
   -o, --output-dir <path>      Output directory
-  -t, --tables <pattern|path>  Table pattern or YAML path
-  --schema <schemas>           Target schemas (comma-separated)
+  --schema <schemas>           Target schemas (comma-separated, default: public)
   --config <path>              Configuration file path
   -f, --force                  Force overwrite
 
-seed command:
-  supatool seed -c <connection> [-t tables.yaml] [-o supabase/seeds]
+Examples:
 
-  tables.yaml format (schema-grouped):
-    public:
-      - users
-      - posts
-    admin:
-      - platforms
+  # Extract full schema
+  supatool extract --all -o db/schemas
 
-  Output: supabase/seeds/<timestamp>/<schema>/<table>_seed.json
-          supabase/seeds/llms.txt  (index for AI)
+  # Multiple schemas and table filter
+  supatool extract --schema public,agent -t "user_*" -o db/schemas
 
-For details, see the documentation.
+  # Deploy (preview first)
+  supatool deploy --table users --dry-run
+  supatool deploy --table all --dry-run
+
+  # Apply migrations
+  supatool migrate --dry-run
+  supatool migrate
+
+  # Seed export
+  supatool seed --tables tables.yaml -o db/seeds
+
+  # tables.yaml format:
+  #   public:
+  #     - users
+  #     - posts
+
+Connection string is read from (in priority order):
+  1. --connection option
+  2. DB_CONNECTION_STRING  (.env.local)
+  3. SUPABASE_CONNECTION_STRING  (legacy)
+  4. DATABASE_URL  (legacy)
+  5. supatool.config.json
+
+For details, see https://github.com/idea-garage/supatool
 `;
 // Model Schema Usage
 exports.modelSchemaHelp = `
@@ -65,8 +78,4 @@ Model Schema Usage (schemas/supatool-data.schema.ts):
   } else {
     console.log('Valid!');
   }
-
-- Use with AI:
-  const schemaJson = JSON.stringify(SUPATOOL_MODEL_SCHEMA, null, 2);
-  // Pass schemaJson to your AI prompt or API
 `;

package/dist/bin/supatool.js

@@ -37,57 +37,62 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // CLI entry point
 // Subcommand support with commander
 const commander_1 = require("commander");
-const index_1 = require("../index");
-const helptext_1 = require("./helptext"); // Import help text from external file
+const helptext_1 = require("./helptext");
 const package_json_1 = require("../../package.json");
 const modelParser_1 = require("../parser/modelParser");
 const docGenerator_1 = require("../generator/docGenerator");
 const typeGenerator_1 = require("../generator/typeGenerator");
-const crudGenerator_1 = require("../generator/crudGenerator");
 const sqlGenerator_1 = require("../generator/sqlGenerator");
 const rlsGenerator_1 = require("../generator/rlsGenerator");
 const sync_1 = require("../sync");
 const definitionExtractor_1 = require("../sync/definitionExtractor");
 const seedGenerator_1 = require("../sync/seedGenerator");
+const migrateRemote_1 = require("../sync/migrateRemote");
 const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
 const program = new commander_1.Command();
 program
     .name('supatool')
     .description('Supatool CLI')
     .version(package_json_1.version);
+function connectionRequiredError() {
+    console.error('Connection string is required. Set it using one of:');
+    console.error('1. --connection option');
+    console.error('2. DB_CONNECTION_STRING environment variable');
+    console.error('3. SUPABASE_CONNECTION_STRING environment variable (legacy)');
+    console.error('4. DATABASE_URL environment variable (legacy)');
+    console.error('5. supatool.config.json configuration file');
+    process.exit(1);
+}
 // extract command
 program
     .command('extract')
-    .description('Extract and categorize database objects from Supabase')
-    .option('-c, --connection <string>', 'Supabase connection string')
-    .option('-o, --output-dir <path>', 'Output directory', './supabase/schemas')
+    .description('Extract and categorize database objects (tables, views, RLS, functions, triggers, types)')
+    .option('-c, --connection <string>', 'Connection string (postgresql:// or postgres://)')
+    .option('-o, --output-dir <path>', 'Output directory', './db/schemas')
     .option('-t, --tables <pattern>', 'Table pattern with wildcards', '*')
     .option('--tables-only', 'Extract only table definitions')
     .option('--views-only', 'Extract only view definitions')
-    .option('--all', 'Extract all DB objects (tables, views, RLS, functions, triggers, cron, types)')
+    .option('--all', 'Extract all DB objects')
     .option('--no-separate', 'Output all objects in same directory')
     .option('--schema <schemas>', 'Target schemas, comma-separated (default: public)')
+    .option('--all-schemas', 'Target all schemas in the DB (use with -e to exclude some)')
+    .option('-e, --exclude-schema <schemas>', 'Schemas to exclude, comma-separated (use with --all-schemas)')
     .option('--config <path>', 'Configuration file path')
     .option('-f, --force', 'Force overwrite without confirmation')
     .action(async (options) => {
     const config = (0, sync_1.resolveConfig)({
         connectionString: options.connection
     }, options.config);
-    if (!config.connectionString) {
-        console.error('Connection string is required. Set it using one of:');
-        console.error('1. --connection option');
-        console.error('2. SUPABASE_CONNECTION_STRING environment variable');
-        console.error('3. DATABASE_URL environment variable');
-        console.error('4. supatool.config.json configuration file');
-        process.exit(1);
-    }
+    if (!config.connectionString)
+        connectionRequiredError();
     try {
-        // Handle --schema option
-        let schemas = ['public']; // default
+        let schemas = ['public'];
         if (options.schema) {
             schemas = options.schema.split(',').map((s) => s.trim());
         }
+        const excludeSchemas = options.excludeSchema
+            ? options.excludeSchema.split(',').map((s) => s.trim())
+            : [];
         await (0, definitionExtractor_1.extractDefinitions)({
             connectionString: config.connectionString,
             outputDir: options.outputDir,
@@ -98,6 +103,8 @@ program
             tablePattern: options.tables,
             force: options.force,
             schemas: schemas,
+            allSchemas: options.allSchemas || false,
+            excludeSchemas,
             version: package_json_1.version
         });
     }
@@ -124,17 +131,6 @@ program
     (0, typeGenerator_1.generateTypesFromModel)(model, options.out);
     console.log('TypeScript types output:', options.out);
 });
-// gen:crud subcommand
-program
-    .command('gen:crud <modelPath>')
-    .description('Generate CRUD TypeScript code from model YAML [deprecated - prefer writing code with LLM]')
-    .option('-o, --out <dir>', 'Output directory', 'docs/generated/crud')
-    .action((modelPath, options) => {
-    console.warn('⚠️  gen:crud is deprecated. With LLM development, writing code as needed is often more efficient.');
-    const model = (0, modelParser_1.parseModelYaml)(modelPath);
-    (0, crudGenerator_1.generateCrudFromModel)(model, options.out);
-    console.log('Generated CRUD TypeScript code:', options.out);
-});
 // gen:docs subcommand
 program
     .command('gen:docs <modelPath>')
@@ -154,12 +150,10 @@ program
     .option('-o, --out <path>', 'Output path', 'docs/generated/schema.sql')
     .action((modelPath, options) => {
     const model = (0, modelParser_1.parseModelYaml)(modelPath);
-    // Write to temp files first
     const tmpSchema = 'docs/generated/.tmp_schema.sql';
     const tmpRls = 'docs/generated/.tmp_rls.sql';
     (0, sqlGenerator_1.generateSqlFromModel)(model, tmpSchema);
     (0, rlsGenerator_1.generateRlsSqlFromModel)(model, tmpRls);
-    // Merge into single file
     const schema = fs.readFileSync(tmpSchema, 'utf-8');
     const rls = fs.readFileSync(tmpRls, 'utf-8');
     fs.writeFileSync(options.out, schema + '\n' + rls);
@@ -177,102 +171,12 @@ program
     (0, rlsGenerator_1.generateRlsSqlFromModel)(model, options.out);
     console.log('RLS/security policy SQL output:', options.out);
 });
-// gen:all subcommand
-program
-    .command('gen:all <modelPath>')
-    .description('Generate all from model YAML')
-    .action((modelPath) => {
-    const model = (0, modelParser_1.parseModelYaml)(modelPath);
-    (0, typeGenerator_1.generateTypesFromModel)(model, 'docs/generated/types.ts');
-    (0, crudGenerator_1.generateCrudFromModel)(model, 'docs/generated/crud');
-    (0, docGenerator_1.generateTableDocMarkdown)(model, 'docs/generated/table-doc.md');
-    (0, docGenerator_1.generateRelationsMarkdown)(model, 'docs/generated/relations.md');
-    console.log('TypeScript types output: docs/generated/types.ts');
-    console.log('CRUD code output: docs/generated/crud/');
-    console.log('Table doc output: docs/generated/table-doc.md');
-    console.log('Relations list output: docs/generated/relations.md');
-});
-// create subcommand
-program
-    .command('create <template>')
-    .description('Generate template YAML')
-    .option('-o, --out <path>', 'Output path', 'docs/model-schema-example.yaml')
-    .action((template, options) => {
-    const srcPath = path.join(__dirname, '../templates/yaml', `${template}.yaml`);
-    const destPath = options.out;
-    if (!fs.existsSync(srcPath)) {
-        console.error(`Template not found: ${srcPath}`);
-        process.exit(1);
-    }
-    fs.copyFileSync(srcPath, destPath);
-    console.log(`Template generated: ${destPath}`);
-});
-// crud command (Supabase types -> CRUD generation)
-program
-    .command('crud')
-    .description('Generate CRUD from Supabase type definitions [deprecated - prefer writing code with LLM]')
-    .option('-i, --input <path>', 'Type definition input path', 'shared/')
-    .option('-o, --output <path>', 'CRUD code output path', 'src/integrations/supabase/')
-    .option('-t, --tables <names>', 'Target tables (comma-separated)')
-    .option('-f, --force', 'Force overwrite output')
-    .action((options) => {
-    console.warn('⚠️  crud is deprecated. With LLM development, writing code as needed is often more efficient.');
-    // Pass argv to main() for CLI args
-    (0, index_1.main)();
-});
-// help subcommand
-program
-    .command('help')
-    .description('Show help')
-    .action(() => {
-    console.log(helptext_1.helpText);
-});
-// sync command (deprecated)
-program
-    .command('sync')
-    .description('Synchronize local and remote schemas [deprecated]')
-    .option('-c, --connection <string>', 'Supabase connection string')
-    .option('-s, --schema-dir <path>', 'Local schema directory', './supabase/schemas')
-    .option('-t, --tables <pattern>', 'Table pattern (wildcards supported)', '*')
-    .option('-f, --force', 'Force overwrite (no confirmation)')
-    .option('--config <path>', 'Configuration file path')
-    .action(async (options) => {
-    console.warn('⚠️  WARNING: sync command is deprecated.');
-    console.warn('   Please use `supatool deploy` command instead.');
-    console.warn('   Example: supatool deploy --table users --dry-run');
-    console.warn('   Example: supatool deploy --table all --dry-run  # all tables');
-    console.warn('');
-    const config = (0, sync_1.resolveConfig)({
-        connectionString: options.connection
-    }, options.config);
-    if (!config.connectionString) {
-        console.error('Connection string is required. Set it using one of:');
-        console.error('1. --connection option');
-        console.error('2. SUPABASE_CONNECTION_STRING environment variable');
-        console.error('3. DATABASE_URL environment variable');
-        console.error('4. supatool.config.json configuration file');
-        process.exit(1);
-    }
-    try {
-        await (0, sync_1.syncAllTables)({
-            connectionString: config.connectionString,
-            schemaDir: options.schemaDir,
-            tablePattern: options.tables,
-            force: options.force,
-            migrationConfig: config.migration
-        });
-    }
-    catch (error) {
-        console.error('⚠️ Sync error:', error);
-        process.exit(1);
-    }
-});
-// deploy command (recommended)
+// deploy command
 program
     .command('deploy')
     .description('Deploy local schema to remote (diff detection, migration generation, confirm before apply)')
-    .option('-c, --connection <string>', 'Supabase connection string')
-    .option('-s, --schema-dir <path>', 'Local schema directory', './supabase/schemas')
+    .option('-c, --connection <string>', 'Connection string (postgresql:// or postgres://)')
+    .option('-s, --schema-dir <path>', 'Local schema directory', './db/schemas')
     .option('-t, --table <name>', 'Target table name (specify "all" for all tables)')
     .option('--auto-apply', 'Auto-apply to remote (no confirmation)')
     .option('--dry-run', 'Preview changes only (recommended)')
@@ -283,27 +187,18 @@ program
     const config = (0, sync_1.resolveConfig)({
         connectionString: options.connection
     }, options.config);
-    if (!config.connectionString) {
-        console.error('Connection string is required. Set it using one of:');
-        console.error('1. --connection option');
-        console.error('2. SUPABASE_CONNECTION_STRING environment variable');
-        console.error('3. DATABASE_URL environment variable');
-        console.error('4. supatool.config.json configuration file');
-        process.exit(1);
-    }
-    // Validate table specification
+    if (!config.connectionString)
+        connectionRequiredError();
     if (!options.table) {
         console.error('❌ Table name is required. Use --table <table-name>');
         console.error('   Example: supatool deploy --table users --dry-run');
-        console.error('   Example: supatool deploy --table all --dry-run  # all tables');
+        console.error('   Example: supatool deploy --table all --dry-run');
         process.exit(1);
     }
     const tablePattern = options.table === 'all' ? '*' : options.table;
-    // Option processing
     const isDryRun = options.dryRun || false;
     const isAutoApply = options.autoApply || false;
     const isGenerateOnly = options.generateOnly || false;
-    // Conflict check
     const activeOptions = [isDryRun, isAutoApply, isGenerateOnly].filter(Boolean).length;
     if (activeOptions > 1) {
         console.error('❌ --dry-run, --auto-apply, --generate-only cannot be specified simultaneously');
@@ -340,27 +235,46 @@ program
         process.exit(1);
     }
 });
+// migrate command — apply pending SQL migration files to remote DB
+program
+    .command('migrate')
+    .description('Apply pending migration files from db/migrations/ to remote DB')
+    .option('-c, --connection <string>', 'Connection string (postgresql:// or postgres://)')
+    .option('-d, --dir <path>', 'Migrations directory', 'db/migrations')
+    .option('--dry-run', 'Preview pending migrations without applying')
+    .option('--config <path>', 'Configuration file path')
+    .action(async (options) => {
+    const config = (0, sync_1.resolveConfig)({
+        connectionString: options.connection
+    }, options.config);
+    if (!config.connectionString)
+        connectionRequiredError();
+    try {
+        await (0, migrateRemote_1.migrateRemote)({
+            connectionString: config.connectionString,
+            migrationsDir: options.dir,
+            dryRun: options.dryRun || false
+        });
+    }
+    catch (error) {
+        console.error('⚠️ Migration error:', error);
+        process.exit(1);
+    }
+});
 // seed command
 program
     .command('seed')
-    .description('Fetch table data from remote DB and generate AI seed JSON')
-    .option('-c, --connection <string>', 'Supabase connection string')
+    .description('Fetch table data from remote DB and generate seed JSON')
+    .option('-c, --connection <string>', 'Connection string (postgresql:// or postgres://)')
     .option('-t, --tables <path>', 'Tables list YAML', 'tables.yaml')
-    .option('-o, --out <dir>', 'Output directory', 'supabase/seeds')
+    .option('-o, --out <dir>', 'Output directory', 'db/seeds')
     .option('--config <path>', 'Configuration file path')
     .action(async (options) => {
-    // Resolve connection
     const config = (0, sync_1.resolveConfig)({
         connectionString: options.connection
     }, options.config);
-    if (!config.connectionString) {
-        console.error('Connection string is required. Set it using one of:');
-        console.error('1. --connection option');
-        console.error('2. SUPABASE_CONNECTION_STRING environment variable');
-        console.error('3. DATABASE_URL environment variable');
-        console.error('4. supatool.config.json configuration file');
-        process.exit(1);
-    }
+    if (!config.connectionString)
+        connectionRequiredError();
     try {
         await (0, seedGenerator_1.generateSeedsFromRemote)({
             connectionString: config.connectionString,
@@ -373,7 +287,14 @@ program
         process.exit(1);
     }
 });
-// If no subcommand is specified, show helpText only (do not call main)
+// help subcommand
+program
+    .command('help')
+    .description('Show help')
+    .action(() => {
+    console.log(helptext_1.helpText);
+});
+// If no subcommand is specified, show helpText only
 if (!process.argv.slice(2).length) {
     console.log(helptext_1.helpText);
     process.exit(0);

package/dist/sync/config.js

@@ -73,12 +73,13 @@ function loadConfig(configPath) {
 function resolveConfig(options, configPath) {
     const fileConfig = loadConfig(configPath);
     const connectionString = options.connectionString ||
+        process.env.DB_CONNECTION_STRING ||
         process.env.SUPABASE_CONNECTION_STRING ||
         process.env.DATABASE_URL ||
         fileConfig.connectionString;
     return {
         connectionString,
-        schemaDir: options.schemaDir || fileConfig.schemaDir || './supabase/schemas',
+        schemaDir: options.schemaDir || fileConfig.schemaDir || './db/schemas',
         tablePattern: options.tablePattern || fileConfig.tablePattern || '*',
         migration: fileConfig.migration
     };
@@ -88,12 +89,12 @@ function resolveConfig(options, configPath) {
  */
 function createConfigTemplate(outputPath) {
     const template = {
-        schemaDir: "./supabase/schemas",
+        schemaDir: "./db/schemas",
         tablePattern: "*",
         migration: {
             naming: "timestamp",
             "_naming_comment": "Use 'sequential' for NNN_description.sql format, 'timestamp' for YYYYMMDDHHMMSS_description.sql",
-            dir: "supabase/migrations"
+            dir: "db/migrations"
         },
         "_comment": "Set credentials in .env.local — never put secrets in this file."
     };
@@ -111,12 +112,12 @@ function ensureEnvLocalTemplate() {
         return;
     const template = [
         '# supatool credentials — never commit this file',
-        '# Option A: Supabase URL + service role key (recommended)',
-        'SUPABASE_URL=https://your-project-ref.supabase.co',
-        'SUPABASE_SERVICE_ROLE_KEY=your-service-role-key',
+        '# PostgreSQL connection string (Cloud SQL, Supabase, or any PostgreSQL)',
+        'DB_CONNECTION_STRING=postgresql://user:password@host:port/database',
         '',
-        '# Option B: direct connection string',
+        '# Legacy aliases (still accepted for backward compatibility)',
         '# SUPABASE_CONNECTION_STRING=postgresql://user:password@host:port/database',
+        '# DATABASE_URL=postgresql://user:password@host:port/database',
     ].join('\n') + '\n';
     fs.writeFileSync(envLocalPath, template, 'utf-8');
     console.log('.env.local template created — fill in your credentials.');