mythik-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,25 @@
 # mythik-cli
 
-Command-line tooling for Mythik specs.
+The AI-first surface to Mythik. The `mythik` command and its
+programmatic sibling (`mythik-cli/api`) are how an AI agent — or a
+human — reads, validates, patches, versions, and promotes Mythik
+specs.
+
+> See [the framework README on GitHub](https://github.com/mldixdev/mythik#readme)
+> for the full Mythik architecture and design philosophy. This file
+> documents what `mythik-cli` gives you and how to use it.
+
+---
+
+## What Mythik is, briefly
+
+Mythik is an **AI-first, spec-driven framework**. Every UI screen and
+API endpoint lives as a JSON spec in a database — not a `.tsx` file
+in a repo. Apps grow by adding rows, not files. The framework
+validates every change atomically, versions everything automatically,
+and promotes between environments (`dev`, `staging`, `production`) by
+atomic pointer move. Your favorite AI agent drives the full workflow
+through this CLI — no GUI in the loop.
 
 ## Install
 
@@ -14,58 +33,197 @@ The package exposes the `mythik` binary:
 npx mythik --help
 ```
 
-## Common Commands
+## The canonical workflow
+
+The Mythik loop is four steps, all served by this package:
 
-```bash
-npx mythik docs path
-npx mythik docs copy ./mythik-docs
-npx mythik manifest home
-npx mythik elements home root,submit-button
-npx mythik validate home
-npx mythik patch home --from-file patch.json
-npx mythik push home --from-file home.json
-npx mythik pull home
-npx mythik lint --from-file home.json
-npx mythik contract --app app-demo --api api-demo
 ```
+       ┌──────────────────────────────────────────────────┐
+       │                                                  │
+       ▼                                                  │
+   manifest  ──▶  elements  ──▶  patch  ──▶  observe
+   (read           (read just     (RFC 6902      (the
+    structure)      what you       diff;           next
+                    need)          atomic          manifest)
+                                   validation
+                                   on push)
+```
+
+Each step is one command:
+
+```bash
+# 1. Read structure
+$ npx mythik manifest task-manager
+
+# 2. Read just the elements you need (use --toon for token-efficient output)
+$ npx mythik elements task-manager task-row,new-task-form --json
+
+# 3. Apply a patch (validates atomically; rejected if it breaks the contract)
+$ npx mythik patch task-manager --from-file add-due-date.json --author claude
+✓ Patch applied. v3 → v4. 4 elements modified.
+
+# 4. Observe — read the new structure
+$ npx mythik manifest task-manager
+```
+
+When `patch` fails (the candidate breaks the contract), the gate
+returns structured diagnostics: rule IDs, paths, suggestion text. The
+agent reads the error, refines the patch, and retries. No half-baked
+write ever lands.
+
+## Moving across environments
+
+`dev`, `staging`, `production` are not deploy targets — they are
+pointers to specific versions of a spec. Move them with `envs`;
+promote across them atomically with `promote`:
+
+```bash
+# Move the dev pointer to the new version
+$ npx mythik envs task-manager --set dev=4 --author claude
+
+# Promote dev → production (validates atomically; rejected if inconsistent)
+$ npx mythik promote task-manager --from dev --to production --confirm --author mldix
+✓ Validated against contract.
+✓ Cross-screen consistency check passed.
+✓ Pointer moved: production v3 → v4.
+
+# List current environment pointers
+$ npx mythik envs task-manager --json
+```
+
+## Read-only previews
 
-Use `--json` for machine-readable output and `--toon` where supported for token-efficient agent workflows.
+For drafts and audits *outside* the canonical loop:
+
+```bash
+# Validate a stored spec (read-only check; no write)
+$ npx mythik validate task-manager
+
+# Lint a local file (draft not yet pushed) or a directory
+$ npx mythik lint --from-file draft.json
+$ npx mythik lint --from-dir ./specs
+
+# Cross-validate a frontend spec against an ApiSpec (catches drift before deploy)
+$ npx mythik contract --app app-demo --api api-demo
+```
+
+All three run the same validators that `patch` and `promote` enforce
+atomically — useful when constructing complex multi-step changes
+locally before committing to a push.
 
-## AI Documentation
+## Store backends
 
-`mythik` bundles the AI documentation corpus inside the core package. Use:
+The CLI can operate against memory, file, Supabase, SQL Server,
+PostgreSQL, MySQL, and SQLite stores. SQL stores share the same edit
+loop: inspect with `manifest`, read exact nodes with `elements`, write
+with `patch --from-file`, then verify.
 
 ```bash
-npx mythik docs path
-```
+# SQLite: local development, demos, tests
+npx mythik init-store --dialect sqlite --target ./mythik.db
+npx mythik patch floor-editor --from-file patch.json --store sqlite --filename ./mythik.db --author ai-agent
 
-Point the AI agent at the printed directory before asking it to create or modify Mythik specs. To copy the docs into a
-project-local folder:
+# PostgreSQL
+npx mythik init-store --dialect postgres --dry-run
+npx mythik patch floor-editor --from-file patch.json --store postgres --url "$DATABASE_URL" --author ai-agent
 
-```bash
-npx mythik docs copy ./mythik-docs
+# MySQL
+npx mythik init-store --dialect mysql --dry-run
+npx mythik patch floor-editor --from-file patch.json --store mysql --url "$DATABASE_URL" --author ai-agent
+
+# SQL Server
+npx mythik init-store --dialect sqlserver --server localhost --database Mythik --user "$DB_USER" --password "$DB_PASSWORD" --encrypt false --trust-server-certificate
+npx mythik patch floor-editor --from-file patch.json --store sqlserver --server localhost --database Mythik --user "$DB_USER" --password "$DB_PASSWORD" --author ai-agent
 ```
+
+`init-store --dry-run` prints the idempotent DDL for review or for a
+team-managed migration pipeline. Runtime reads and writes do not
+silently create missing store tables. MySQL generated upsert SQL
+targets MySQL 8.0.19+.
+
+## History and rollback
+
+```bash
+# Show version history with structural diffs
+$ npx mythik history task-manager
+
+# Compare two versions or two environments
+$ npx mythik diff task-manager 3 4
+$ npx mythik diff task-manager dev production
+
+# Always-forward rollback (creates a new version with old content)
+$ npx mythik rollback task-manager --to 3 --author mldix
+```
+
+Rollback never rewrites history. The new version `v5` will hold the
+content of `v3`. `v4` stays in the history with its own author and
+timestamp.
+
+## Output formats
+
+| Flag | When to use |
+|---|---|
+| `--json` | Machine-readable output for scripts and IDE integrations |
+| `--toon` (where supported) | Token-efficient agent reads — same shape, fewer tokens, useful for paginating large manifests or element catalogs |
 
 ## Programmatic API
 
-Use `mythik-cli/api` when a script, IDE integration, or AI agent should avoid shell quoting issues:
+When a script, IDE integration, or AI agent should avoid shell
+quoting, use `mythik-cli/api`:
 
 ```ts
-import { runPatch, runPush, runLint } from 'mythik-cli/api';
+import { runPatch, runValidate, runPromote } from 'mythik-cli/api';
 
-await runPatch({
-  screen: 'home',
-  fromFile: 'patch.json',
+const result = await runPatch({
+  screen: 'task-manager',
+  fromFile: 'add-due-date.json',
+  author: 'claude',
   json: true,
 });
+
+if (!result.ok) {
+  console.error(result.diagnostics);
+}
 ```
 
-The programmatic API uses the same implementation path as the CLI.
+The programmatic API uses the same implementation path as the binary —
+nothing is special-cased. Whatever the CLI does, the API does
+identically.
 
-## License
+## Bundled AI documentation
 
-Apache-2.0.
+The `mythik` package (peer dependency) ships canonical AI docs at
+`node_modules/mythik/docs/`. Locate or copy them:
+
+```bash
+$ npx mythik docs path
+/your-project/node_modules/mythik/docs
+
+$ npx mythik docs copy ./mythik-docs
+```
+
+Point your AI agent at the printed path before asking it to author or
+modify specs. Inside that directory:
+
+- `consumer/ai-context.md` — spec-generation primer (rules and traps)
+- `consumer/ai-context-primitives.md` — every primitive's props
+- `consumer/reference-doc.md` — full rule catalog
+- `wiki/compiled/` — atomic per-concept articles (one page per action,
+  primitive, rule, expression) optimized for AI lookup
+- `llms.txt` — index for AI tools that read it
+
+## Related packages
+
+- [`mythik`](https://github.com/mldixdev/mythik/tree/main/packages/core#readme) — the runtime this CLI manipulates
+- [`mythik-react`](https://github.com/mldixdev/mythik/tree/main/packages/react#readme) — render the specs as a React app
+- [`mythik-server`](https://github.com/mldixdev/mythik/tree/main/packages/server#readme) — declarative REST server from an `ApiSpec`
 
 ## Status
 
-v0.1.1 public release. The binary name is `mythik`; the npm package name is `mythik-cli`.
+Public release line. The binary name is `mythik`; the npm package name
+is `mythik-cli`. APIs are documented for real-world feedback as the
+framework evolves.
+
+## License
+
+Apache-2.0.

package/dist/api.d.ts

@@ -15,6 +15,8 @@ export { runPatch, parsePatchInput } from './commands/patch.js';
 export type { PatchOptions } from './commands/patch.js';
 export { runDocsCommand, resolveBundledDocsRoot } from './commands/docs.js';
 export type { DocsCommandOptions, DocsCommandResult } from './commands/docs.js';
+export { runInitStore } from './commands/init-store.js';
+export type { InitStoreOptions } from './commands/init-store.js';
 export type { CommandResult } from './commands/manifest.js';
 export type { SpecStore, JsonPatch, ValidationError, PatchResult } from 'mythik';
 export { runLint } from './lint/orchestrator.js';

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG5D,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAGjF,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG5D,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAGjF,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/api.js

@@ -12,6 +12,7 @@
 export { runPush } from './commands/push.js';
 export { runPatch, parsePatchInput } from './commands/patch.js';
 export { runDocsCommand, resolveBundledDocsRoot } from './commands/docs.js';
+export { runInitStore } from './commands/init-store.js';
 // Lint API — runLint + types (v49 Item I)
 export { runLint } from './lint/orchestrator.js';
 //# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAQ5E,0CAA0C;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAQxD,0CAA0C;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { loadConfig } from './config.js';
+import { loadConfig, withStoreTableOverride } from './config.js';
 import { resolveStore } from './stores/resolver.js';
 import { runManifest } from './commands/manifest.js';
 import { runElements } from './commands/elements.js';
 import { runPatch, parsePatchInput } from './commands/patch.js';
 import { runValidate } from './commands/validate.js';
 import { runInit } from './commands/init.js';
+import { runInitStore } from './commands/init-store.js';
 import { runPull } from './commands/pull.js';
 import { runPush } from './commands/push.js';
 import { runDelete } from './commands/delete.js';
@@ -23,19 +24,26 @@ import { runDocsCommand } from './commands/docs.js';
 import { resolveInput } from './input-resolver.js';
 import { runPushBulk } from './commands/push-bulk.js';
 const program = new Command();
+const STORE_HELP = 'Store type (supabase, sqlserver, postgres, mysql, sqlite, file, memory)';
 program
     .name('mythik')
     .description('Mythik CLI — manage specs via SpecEngine')
-    .version('0.1.1');
+    .version('0.1.3');
 program
     .command('manifest <screen>')
     .description('Show structural tree of a screen spec')
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type (supabase, file, memory)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (screen, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -54,11 +62,17 @@ program
     .description('Show details of specific elements by ID (comma-separated)')
     .option('--json', 'Output as JSON', false)
     .option('--toon', 'Output in TOON format (token-efficient)', false)
-    .option('--store <type>', 'Store type (supabase, file, memory)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (screen, ids, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -81,11 +95,17 @@ program
     .option('--author <name>', 'Author name for version history')
     .option('--description <text>', 'Description for version history')
     .option('--from-file <path>', 'Read patches from file (use "-" for stdin)')
-    .option('--store <type>', 'Store type (supabase, file, memory)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (screen, patchesArg, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -122,11 +142,17 @@ program
     .command('validate <screen>')
     .description('Validate a screen spec for errors')
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type (supabase, file, memory)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (screen, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -143,11 +169,17 @@ program
 program
     .command('init')
     .description('Initialize Mythik CLI configuration')
-    .option('--store <type>', 'Store type (supabase, file, memory)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (opts) => {
     try {
         const result = await runInit(opts, process.cwd());
@@ -161,6 +193,43 @@ program
         process.exit(1);
     }
 });
+program
+    .command('init-store')
+    .description('Initialize Mythik-managed SQL store tables')
+    .requiredOption('--dialect <dialect>', 'SQL dialect (sqlserver, postgres, mysql, sqlite)')
+    .option('--target <file>', 'SQLite database file target')
+    .option('--url <url>', 'Database URL for PostgreSQL, MySQL, or SQL Server')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL Server user')
+    .option('--password <password>', 'SQL Server password')
+    .option('--port <port>', 'SQL Server port')
+    .option('--encrypt <value>', 'SQL Server encrypt option (true or false)')
+    .option('--trust-server-certificate', 'Trust SQL Server self-signed certificates')
+    .option('--dry-run', 'Print canonical DDL without connecting', false)
+    .action(async (opts) => {
+    try {
+        const result = await runInitStore({
+            dialect: opts.dialect,
+            target: opts.target,
+            url: opts.url,
+            server: opts.server,
+            database: opts.database,
+            user: opts.user,
+            password: opts.password,
+            port: opts.port,
+            encrypt: opts.encrypt,
+            trustServerCertificate: opts.trustServerCertificate === true,
+            dryRun: opts.dryRun === true,
+        });
+        process.stdout.write(result.output + '\n');
+        process.exit(result.exitCode);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+});
 program
     .command('push [screen]')
     .description('Create or replace screen spec(s) from stdin, --from-file, or --from-dir')
@@ -170,11 +239,17 @@ program
     .option('--description <text>', 'Description for version history')
     .option('--from-file <path>', 'Read spec from file (use "-" for stdin)')
     .option('--from-dir <folder>', 'Push every *.json file in <folder> (filename stem = spec id)')
-    .option('--store <type>', 'Store type (supabase, file, memory, sqlserver)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (screen, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -232,11 +307,17 @@ program
     .description('Export a full screen spec to stdout')
     .option('--json', 'Wrap output in JSON object', false)
     .option('--toon', 'Output in TOON format', false)
-    .option('--store <type>', 'Store type (supabase, file, memory, sqlserver)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (screen, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -255,11 +336,17 @@ program
     .description('Delete a screen spec from the store')
     .option('--confirm', 'Actually delete (without this flag, preview only)', false)
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type (supabase, file, memory, sqlserver)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (screen, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -284,11 +371,17 @@ program
     .option('--base-url <url>', 'Base URL to strip from fetch URLs')
     .option('--api-table <table>', 'Table name for api-specs (when stored separately)')
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type (supabase, file, memory, sqlserver)')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
     .option('--url <url>', 'Supabase URL')
     .option('--key <key>', 'Supabase API key')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
     .option('--dir <dir>', 'File store directory')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -297,12 +390,7 @@ program
         // If --api-table is provided, create a separate store for api-specs
         let apiStore;
         if (opts.apiTable) {
-            const apiConfig = { ...config };
-            if (apiConfig.sqlserver)
-                apiConfig.sqlserver = { ...apiConfig.sqlserver, table: opts.apiTable };
-            if (apiConfig.supabase)
-                apiConfig.supabase = { ...apiConfig.supabase, table: opts.apiTable };
-            apiStore = resolveStore(apiConfig);
+            apiStore = resolveStore(withStoreTableOverride(config, opts.apiTable));
         }
         const result = await runContractCommand({
             store,
@@ -326,8 +414,18 @@ program
     .description('Show version history for a spec')
     .option('--limit <n>', 'Limit number of versions shown', parseInt)
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
+    .option('--versions-table <name>', 'SQL version history table name')
+    .option('--environments-table <name>', 'SQL environment pointer table name')
+    .option('--snapshot-interval <n>', 'SQL version snapshot interval')
+    .option('--url <url>', 'Database URL')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (specId, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -345,8 +443,18 @@ program
     .command('diff <specId> <from> [to]')
     .description('Show structural diff between two versions or environments')
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
+    .option('--versions-table <name>', 'SQL version history table name')
+    .option('--environments-table <name>', 'SQL environment pointer table name')
+    .option('--snapshot-interval <n>', 'SQL version snapshot interval')
+    .option('--url <url>', 'Database URL')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (specId, from, to, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -366,8 +474,18 @@ program
     .option('--set <env=version>', 'Set environment pointer (e.g., --set dev=12)')
     .option('--author <name>', 'Author for set operation')
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
+    .option('--versions-table <name>', 'SQL version history table name')
+    .option('--environments-table <name>', 'SQL environment pointer table name')
+    .option('--snapshot-interval <n>', 'SQL version snapshot interval')
+    .option('--url <url>', 'Database URL')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (specId, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -389,8 +507,18 @@ program
     .option('--author <name>', 'Author name', 'system')
     .option('--description <text>', 'Description for the rollback version')
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
+    .option('--versions-table <name>', 'SQL version history table name')
+    .option('--environments-table <name>', 'SQL environment pointer table name')
+    .option('--snapshot-interval <n>', 'SQL version snapshot interval')
+    .option('--url <url>', 'Database URL')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (specId, opts) => {
     try {
         const config = loadConfig({ flags: opts });
@@ -416,8 +544,18 @@ program
     .option('--confirm', 'Execute promotion (without this, preview only)', false)
     .option('--author <name>', 'Author name', 'system')
     .option('--json', 'Output as JSON', false)
-    .option('--store <type>', 'Store type')
+    .option('--store <type>', STORE_HELP)
     .option('--table <name>', 'Table name override (e.g., api_specs)')
+    .option('--versions-table <name>', 'SQL version history table name')
+    .option('--environments-table <name>', 'SQL environment pointer table name')
+    .option('--snapshot-interval <n>', 'SQL version snapshot interval')
+    .option('--url <url>', 'Database URL')
+    .option('--server <host>', 'SQL Server host')
+    .option('--database <name>', 'SQL Server database name')
+    .option('--user <user>', 'SQL database user')
+    .option('--password <password>', 'SQL database password')
+    .option('--port <port>', 'SQL database port')
+    .option('--filename <file>', 'SQLite database file')
     .action(async (specIds, opts) => {
     try {
         const config = loadConfig({ flags: opts });