@kweaver-ai/kweaver-sdk 0.8.2 → 0.8.3

package/dist/commands/vega.js

@@ -3,50 +3,51 @@ import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/
 import { vegaHealth, listVegaCatalogs, getVegaCatalog, createVegaCatalog, updateVegaCatalog, deleteVegaCatalogs, vegaCatalogHealthStatus, testVegaCatalogConnection, discoverVegaCatalog, listVegaCatalogResources, listVegaResources, getVegaResource, queryVegaResourceData, createVegaResource, updateVegaResource, deleteVegaResources, listVegaConnectorTypes, getVegaConnectorType, registerVegaConnectorType, updateVegaConnectorType, deleteVegaConnectorType, setVegaConnectorTypeEnabled, createVegaDatasetDocs, updateVegaDatasetDocs, deleteVegaDatasetDocs, deleteVegaDatasetDocsQuery, buildVegaDataset, getVegaDatasetBuildStatus, executeVegaQuery, vegaSQLQuery, listAllVegaResources, } from "../api/vega.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
+import { renderHelp } from "../help/format.js";
 // ---------------------------------------------------------------------------
 // Help
 // ---------------------------------------------------------------------------
+const VEGA_HELP = renderHelp({
+    tagline: "Vega observability — catalogs, resources, datasets, queries, connector types",
+    usage: "kweaver vega <subcommand> [<action>] [flags]",
+    sections: [
+        {
+            title: "SERVICE",
+            items: [
+                { name: "health", desc: "Check Vega service health" },
+                { name: "stats", desc: "Show catalog statistics" },
+                { name: "inspect", desc: "Health + catalog summary + running tasks" },
+            ],
+        },
+        {
+            title: "RESOURCES",
+            items: [
+                { name: "catalog", desc: "list / get / health / test-connection / discover / resources / create / update / delete" },
+                { name: "resource", desc: "list / get / query / create / update / delete / list-all" },
+                { name: "dataset", desc: "create-docs / update-docs / delete-docs / delete-docs-query / build / build-status" },
+                { name: "query", desc: "execute — structured query (tables, joins, filters)" },
+                { name: "sql", desc: "Direct SQL / DSL; use {{<resource_id>}} in SQL (quoted)" },
+                { name: "connector-type", desc: "list / get / register / update / delete / enable" },
+            ],
+        },
+    ],
+    flags: [
+        { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+        { name: "--pretty", desc: "Pretty-print JSON (default)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver vega health",
+        "kweaver vega catalog list --status active",
+        "kweaver vega sql --resource-type elasticsearch --query 'SELECT * FROM {{r-123}} LIMIT 10'",
+    ],
+    learnMore: [
+        "Use `kweaver help all` for full per-action signatures",
+        "Use `kweaver vega <subcommand> --help` for action-level details (where supported)",
+    ],
+});
 function printVegaHelp() {
-    console.log(`kweaver vega
-
-Subcommands:
-  health                              Check Vega service health
-  stats                               Show catalog statistics
-  inspect                             Health + catalog summary + running tasks
-  catalog list [--status X] [--limit N] [--offset N]
-  catalog get <id>
-  catalog health <ids...> | --all     Health-check catalogs
-  catalog test-connection <id>        Test catalog connectivity
-  catalog discover <id> [--wait]      Trigger discovery
-  catalog resources <id> [--category X] [--limit N]
-  catalog create --name <n> --connector-type <t> --connector-config <json>
-  catalog update <id> [--name X] [--connector-type X] [--tags X] [--description X]
-  catalog delete <ids...> [-y]
-  resource list [--catalog-id X] [--category X] [--status X] [--limit N] [--offset N]
-  resource get <id>
-  resource query <id> -d <json-body>  Query resource data
-  resource create --catalog-id <cid> --name <n> --category <cat>
-  resource update <id> [--name X] [--status X] [--tags X] [-d json]
-  resource delete <ids...> [-y]
-  resource list-all [--limit N] [--offset N]
-  dataset create-docs <resource-id> -d <json-array>
-  dataset update-docs <resource-id> -d <json-array>
-  dataset delete-docs <resource-id> <doc-ids...>
-  dataset delete-docs-query <resource-id> -d <filter-json>
-  dataset build <resource-id> [--mode full|incremental|realtime]
-  dataset build-status <resource-id> <task-id>
-  query execute -d <json>               Structured query (tables, joins, filters)
-  sql --resource-type <t> --query <sql>  Direct SQL / DSL; use {{<resource_id>}} in SQL (quoted)
-  sql -d <json>                         Same API with full JSON body (advanced)
-  connector-type list                 List connector types
-  connector-type get <type>           Get connector type details
-  connector-type register -d <json>   Register a new connector type
-  connector-type update <type> -d <json>  Update connector type
-  connector-type delete <type> [-y]   Delete connector type
-  connector-type enable <type> --enabled <bool>  Enable/disable connector type
-Common flags:
-  -bd, --biz-domain <s>   Business domain (default: bd_public)
-  --pretty                Pretty-print JSON (default)`);
+    console.log(VEGA_HELP);
 }
 // ---------------------------------------------------------------------------
 // Common flag parser
@@ -131,7 +132,10 @@ export async function runVegaCommand(args) {
 // ---------------------------------------------------------------------------
 async function runVegaHealthCommand(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("kweaver vega health\n\nCheck Vega service health.");
+        console.log(renderHelp({
+            tagline: "Check Vega service health.",
+            usage: "kweaver vega health [flags]",
+        }));
         return 0;
     }
     const { businessDomain, pretty } = parseCommonFlags(args);
@@ -149,7 +153,10 @@ async function runVegaHealthCommand(args) {
 // ---------------------------------------------------------------------------
 async function runVegaStatsCommand(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("kweaver vega stats\n\nShow catalog statistics.");
+        console.log(renderHelp({
+            tagline: "Show catalog statistics.",
+            usage: "kweaver vega stats [flags]",
+        }));
         return 0;
     }
     const { businessDomain, pretty } = parseCommonFlags(args);
@@ -178,7 +185,10 @@ async function runVegaStatsCommand(args) {
 // ---------------------------------------------------------------------------
 async function runVegaInspectCommand(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("kweaver vega inspect\n\nHealth + catalog summary.");
+        console.log(renderHelp({
+            tagline: "Health + catalog summary.",
+            usage: "kweaver vega inspect [flags]",
+        }));
         return 0;
     }
     const { businessDomain, pretty } = parseCommonFlags(args);
@@ -214,18 +224,26 @@ async function runVegaInspectCommand(args) {
 async function runVegaCatalogCommand(args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "--help" || sub === "-h") {
-        console.log(`kweaver vega catalog
-
-Subcommands:
-  list [--status X] [--limit N] [--offset N]
-  get <id>
-  health <ids...> | --all
-  test-connection <id>
-  discover <id> [--wait]
-  resources <id> [--category X] [--limit N]
-  create --name <name> --connector-type <type> --connector-config <json> [--tags t1,t2] [--description X]
-  update <id> [--name X] [--connector-type X] [--tags X] [--description X] [--connector-config X]
-  delete <ids...> [-y]`);
+        console.log(renderHelp({
+            tagline: "Manage Vega catalogs.",
+            usage: "kweaver vega catalog <subcommand> [flags]",
+            sections: [
+                {
+                    title: "AVAILABLE COMMANDS",
+                    items: [
+                        { name: "list", desc: "List catalogs (filter by status, paginate)" },
+                        { name: "get", desc: "Get catalog by id" },
+                        { name: "health", desc: "Health-check one or more catalogs (or --all)" },
+                        { name: "test-connection", desc: "Test catalog connectivity" },
+                        { name: "discover", desc: "Trigger discovery for a catalog" },
+                        { name: "resources", desc: "List resources within a catalog" },
+                        { name: "create", desc: "Create a catalog (name + connector-type + config)" },
+                        { name: "update", desc: "Update catalog fields" },
+                        { name: "delete", desc: "Delete one or more catalogs (-y to skip confirm)" },
+                    ],
+                },
+            ],
+        }));
         return 0;
     }
     if (sub === "list")
@@ -254,14 +272,17 @@ Subcommands:
 // ---------------------------------------------------------------------------
 async function runCatalogList(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega catalog list [options]
-
-Options:
-  --status <s>    Filter by status
-  --limit <n>     Max results (default: 30)
-  --offset <n>    Offset
-  -bd, --biz-domain  Business domain (default: bd_public)
-  --pretty         Pretty-print JSON (default)`);
+        console.log(renderHelp({
+            tagline: "List Vega catalogs.",
+            usage: "kweaver vega catalog list [flags]",
+            flags: [
+                { name: "--status <s>", desc: "Filter by status" },
+                { name: "--limit <n>", desc: "Max results (default: 30)" },
+                { name: "--offset <n>", desc: "Offset" },
+                { name: "-bd, --biz-domain", desc: "Business domain (default: bd_public)" },
+                { name: "--pretty", desc: "Pretty-print JSON (default)" },
+            ],
+        }));
         return 0;
     }
     let status;
@@ -300,7 +321,10 @@ Options:
 // ---------------------------------------------------------------------------
 async function runCatalogGet(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("kweaver vega catalog get <id>");
+        console.log(renderHelp({
+            tagline: "Get a Vega catalog by ID.",
+            usage: "kweaver vega catalog get <id> [flags]",
+        }));
         return 0;
     }
     const { remaining, businessDomain, pretty } = parseCommonFlags(args);
@@ -324,10 +348,18 @@ async function runCatalogGet(args) {
 // ---------------------------------------------------------------------------
 async function runCatalogHealth(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega catalog health <ids...> | --all
-
-Options:
-  --all   Check health of all catalogs`);
+        console.log(renderHelp({
+            tagline: "Check health of one or more Vega catalogs.",
+            usage: "kweaver vega catalog health <ids...> | --all",
+            flags: [
+                { name: "--all", desc: "Check health of all catalogs" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver vega catalog health c-123 c-456",
+                "kweaver vega catalog health --all",
+            ],
+        }));
         return 0;
     }
     const { remaining, businessDomain, pretty } = parseCommonFlags(args);
@@ -365,7 +397,12 @@ Options:
 // ---------------------------------------------------------------------------
 async function runCatalogTestConnection(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("kweaver vega catalog test-connection <id>");
+        console.log(renderHelp({
+            tagline: "Test catalog connector connectivity.",
+            usage: "kweaver vega catalog test-connection <id>",
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: ["kweaver vega catalog test-connection c-123"],
+        }));
         return 0;
     }
     const { remaining, businessDomain, pretty } = parseCommonFlags(args);
@@ -389,10 +426,18 @@ async function runCatalogTestConnection(args) {
 // ---------------------------------------------------------------------------
 async function runCatalogDiscover(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega catalog discover <id> [--wait]
-
-Options:
-  --wait   Wait for discovery to complete`);
+        console.log(renderHelp({
+            tagline: "Trigger catalog resource discovery.",
+            usage: "kweaver vega catalog discover <id> [--wait]",
+            flags: [
+                { name: "--wait", desc: "Wait for discovery to complete" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver vega catalog discover c-123",
+                "kweaver vega catalog discover c-123 --wait",
+            ],
+        }));
         return 0;
     }
     const { remaining, businessDomain, pretty } = parseCommonFlags(args);
@@ -418,11 +463,19 @@ Options:
 // ---------------------------------------------------------------------------
 async function runCatalogResources(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega catalog resources <id> [options]
-
-Options:
-  --category <s>   Filter by category
-  --limit <n>      Max results (default: 30)`);
+        console.log(renderHelp({
+            tagline: "List resources for a catalog.",
+            usage: "kweaver vega catalog resources <id> [flags]",
+            flags: [
+                { name: "--category <s>", desc: "Filter by category" },
+                { name: "--limit <n>", desc: "Max results (default: 30)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver vega catalog resources c-123",
+                "kweaver vega catalog resources c-123 --category table --limit 50",
+            ],
+        }));
         return 0;
     }
     let category;
@@ -465,14 +518,21 @@ Options:
 // ---------------------------------------------------------------------------
 async function runCatalogCreate(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega catalog create [options]
-
-Options:
-  --name <s>              Catalog name (required)
-  --connector-type <s>    Connector type (required)
-  --connector-config <j>  Connector config JSON (required)
-  --tags <t1,t2>          Comma-separated tags
-  --description <s>       Description`);
+        console.log(renderHelp({
+            tagline: "Create a Vega catalog.",
+            usage: "kweaver vega catalog create [flags]",
+            flags: [
+                { name: "--name <s>", desc: "Catalog name (required)" },
+                { name: "--connector-type <s>", desc: "Connector type (required)" },
+                { name: "--connector-config <j>", desc: "Connector config JSON (required)" },
+                { name: "--tags <t1,t2>", desc: "Comma-separated tags" },
+                { name: "--description <s>", desc: "Description" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver vega catalog create --name my-cat --connector-type mysql --connector-config '{\"host\":\"...\"}'",
+            ],
+        }));
         return 0;
     }
     let name;
@@ -532,14 +592,22 @@ Options:
 // ---------------------------------------------------------------------------
 async function runCatalogUpdate(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega catalog update <id> [options]
-
-Options:
-  --name <s>              New name
-  --connector-type <t>    Connector type (e.g. mysql, opensearch)
-  --tags <t1,t2>          Comma-separated tags
-  --description <s>       Description
-  --connector-config <j>  Connector config JSON`);
+        console.log(renderHelp({
+            tagline: "Update a Vega catalog.",
+            usage: "kweaver vega catalog update <id> [flags]",
+            flags: [
+                { name: "--name <s>", desc: "New name" },
+                { name: "--connector-type <t>", desc: "Connector type (e.g. mysql, opensearch)" },
+                { name: "--tags <t1,t2>", desc: "Comma-separated tags" },
+                { name: "--description <s>", desc: "Description" },
+                { name: "--connector-config <j>", desc: "Connector config JSON" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver vega catalog update c-123 --name new-name",
+                "kweaver vega catalog update c-123 --tags prod,critical",
+            ],
+        }));
         return 0;
     }
     let name;
@@ -607,10 +675,18 @@ Options:
 // ---------------------------------------------------------------------------
 async function runCatalogDelete(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega catalog delete <ids...> [-y]
-
-Options:
-  -y, --yes   Skip confirmation`);
+        console.log(renderHelp({
+            tagline: "Delete one or more Vega catalogs.",
+            usage: "kweaver vega catalog delete <ids...> [-y]",
+            flags: [
+                { name: "-y, --yes", desc: "Skip confirmation" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver vega catalog delete c-123",
+                "kweaver vega catalog delete c-123 c-456 -y",
+            ],
+        }));
         return 0;
     }
     let skipConfirm = false;
@@ -654,16 +730,25 @@ Options:
 async function runVegaResourceCommand(args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "--help" || sub === "-h") {
-        console.log(`kweaver vega resource
-
-Subcommands:
-  list [--catalog-id X] [--category X] [--status X] [--limit N] [--offset N]
-  list-all [--limit N] [--offset N]
-  get <id>
-  query <id> -d <json-body>
-  create --catalog-id <cid> --name <name> --category <cat>
-  update <id> [--name X] [--status X] [--tags X] [-d json]
-  delete <ids...> [-y]`);
+        console.log(renderHelp({
+            tagline: "Manage Vega resources.",
+            usage: "kweaver vega resource <subcommand> [flags]",
+            sections: [
+                {
+                    title: "AVAILABLE COMMANDS",
+                    items: [
+                        { name: "list", desc: "List resources (filter by catalog / category / status)" },
+                        { name: "list-all", desc: "List all resources across catalogs" },
+                        { name: "get", desc: "Get resource by id" },
+                        { name: "query", desc: "Query resource data (JSON body)" },
+                        { name: "create", desc: "Create a resource (--catalog-id --name --category)" },
+                        { name: "update", desc: "Update resource fields" },
+                        { name: "delete", desc: "Delete one or more resources (-y to skip confirm)" },
+                    ],
+                },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     if (sub === "list")
@@ -688,16 +773,20 @@ Subcommands:
 // ---------------------------------------------------------------------------
 async function runResourceList(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega resource list [options]
-
-Options:
-  --catalog-id <s>  Filter by catalog
-  --category <s>    Filter by category
-  --status <s>      Filter by status
-  --limit <n>       Max results (default: 30)
-  --offset <n>      Offset
-  -bd, --biz-domain  Business domain (default: bd_public)
-  --pretty           Pretty-print JSON (default)`);
+        console.log(renderHelp({
+            tagline: "List Vega resources.",
+            usage: "kweaver vega resource list [flags]",
+            flags: [
+                { name: "--catalog-id <s>", desc: "Filter by catalog" },
+                { name: "--category <s>", desc: "Filter by category" },
+                { name: "--status <s>", desc: "Filter by status" },
+                { name: "--limit <n>", desc: "Max results (default: 30)" },
+                { name: "--offset <n>", desc: "Offset" },
+                { name: "-bd, --biz-domain", desc: "Business domain (default: bd_public)" },
+                { name: "--pretty", desc: "Pretty-print JSON (default)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let catalogId;
@@ -748,13 +837,17 @@ Options:
 // ---------------------------------------------------------------------------
 async function runResourceListAll(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega resource list-all [options]
-
-Options:
-  --limit <n>       Max results (default: 30)
-  --offset <n>      Offset
-  -bd, --biz-domain  Business domain (default: bd_public)
-  --pretty           Pretty-print JSON (default)`);
+        console.log(renderHelp({
+            tagline: "List all Vega resources.",
+            usage: "kweaver vega resource list-all [flags]",
+            flags: [
+                { name: "--limit <n>", desc: "Max results (default: 30)" },
+                { name: "--offset <n>", desc: "Offset" },
+                { name: "-bd, --biz-domain", desc: "Business domain (default: bd_public)" },
+                { name: "--pretty", desc: "Pretty-print JSON (default)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let limit = 30;
@@ -787,7 +880,11 @@ Options:
 // ---------------------------------------------------------------------------
 async function runResourceGet(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("kweaver vega resource get <id>");
+        console.log(renderHelp({
+            tagline: "Get a Vega resource by id.",
+            usage: "kweaver vega resource get <id> [flags]",
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     const { remaining, businessDomain, pretty } = parseCommonFlags(args);
@@ -811,10 +908,14 @@ async function runResourceGet(args) {
 // ---------------------------------------------------------------------------
 async function runResourceQuery(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega resource query <id> -d <json-body>
-
-Options:
-  -d, --data <json>   Request body (JSON string)`);
+        console.log(renderHelp({
+            tagline: "Query a Vega resource.",
+            usage: "kweaver vega resource query <id> -d <json-body> [flags]",
+            flags: [
+                { name: "-d, --data <json>", desc: "Request body (JSON string)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let data;
@@ -851,15 +952,19 @@ Options:
 // ---------------------------------------------------------------------------
 async function runResourceCreate(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega resource create [options]
-
-Options:
-  --catalog-id <cid>          Catalog ID (required)
-  --name <name>               Resource name (required)
-  --category <cat>            Category (required)
-  --source-identifier <si>    Source identifier
-  --database <db>             Database name
-  -d, --data <json>           Additional fields as JSON`);
+        console.log(renderHelp({
+            tagline: "Create a Vega resource.",
+            usage: "kweaver vega resource create [flags]",
+            flags: [
+                { name: "--catalog-id <cid>", desc: "Catalog ID (required)" },
+                { name: "--name <name>", desc: "Resource name (required)" },
+                { name: "--category <cat>", desc: "Category (required)" },
+                { name: "--source-identifier <si>", desc: "Source identifier" },
+                { name: "--database <db>", desc: "Database name" },
+                { name: "-d, --data <json>", desc: "Additional fields as JSON" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let catalogId;
@@ -922,13 +1027,17 @@ Options:
 // ---------------------------------------------------------------------------
 async function runResourceUpdate(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega resource update <id> [options]
-
-Options:
-  --name <name>       Resource name
-  --status <s>        Status
-  --tags <t1,t2>      Comma-separated tags
-  -d, --data <json>   Additional fields as JSON`);
+        console.log(renderHelp({
+            tagline: "Update a Vega resource.",
+            usage: "kweaver vega resource update <id> [flags]",
+            flags: [
+                { name: "--name <name>", desc: "Resource name" },
+                { name: "--status <s>", desc: "Status" },
+                { name: "--tags <t1,t2>", desc: "Comma-separated tags" },
+                { name: "-d, --data <json>", desc: "Additional fields as JSON" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let name;
@@ -988,10 +1097,14 @@ Options:
 // ---------------------------------------------------------------------------
 async function runResourceDelete(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega resource delete <ids...> [-y]
-
-Options:
-  -y, --yes   Skip confirmation prompt`);
+        console.log(renderHelp({
+            tagline: "Delete Vega resources.",
+            usage: "kweaver vega resource delete <ids...> [flags]",
+            flags: [
+                { name: "-y, --yes", desc: "Skip confirmation prompt" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let yes = false;
@@ -1033,15 +1146,24 @@ Options:
 async function runVegaDatasetCommand(args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "--help" || sub === "-h") {
-        console.log(`kweaver vega dataset
-
-Subcommands:
-  create-docs <resource-id> -d <json-array>
-  update-docs <resource-id> -d <json-array>
-  delete-docs <resource-id> <doc-ids...>
-  delete-docs-query <resource-id> -d <filter-json>
-  build <resource-id> [--mode full|incremental|realtime]
-  build-status <resource-id> <task-id>`);
+        console.log(renderHelp({
+            tagline: "Manage Vega dataset documents and builds.",
+            usage: "kweaver vega dataset <subcommand> [flags]",
+            sections: [
+                {
+                    title: "AVAILABLE COMMANDS",
+                    items: [
+                        { name: "create-docs", desc: "Create documents in a dataset resource" },
+                        { name: "update-docs", desc: "Update documents (by id) in a dataset resource" },
+                        { name: "delete-docs", desc: "Delete documents by id" },
+                        { name: "delete-docs-query", desc: "Delete documents by filter query" },
+                        { name: "build", desc: "Build a dataset (full / incremental / realtime)" },
+                        { name: "build-status", desc: "Get build task status" },
+                    ],
+                },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     if (sub === "create-docs")
@@ -1064,10 +1186,14 @@ Subcommands:
 // ---------------------------------------------------------------------------
 async function runDatasetCreateDocs(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega dataset create-docs <resource-id> -d <json-array>
-
-Options:
-  -d, --data <json>   Array of documents (JSON string)`);
+        console.log(renderHelp({
+            tagline: "Create dataset documents.",
+            usage: "kweaver vega dataset create-docs <resource-id> -d <json-array>",
+            flags: [
+                { name: "-d, --data <json>", desc: "Array of documents (JSON string)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let data;
@@ -1103,10 +1229,14 @@ Options:
 // ---------------------------------------------------------------------------
 async function runDatasetUpdateDocs(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega dataset update-docs <resource-id> -d <json-array>
-
-Options:
-  -d, --data <json>   Array of documents with ids (JSON string)`);
+        console.log(renderHelp({
+            tagline: "Update dataset documents.",
+            usage: "kweaver vega dataset update-docs <resource-id> -d <json-array>",
+            flags: [
+                { name: "-d, --data <json>", desc: "Array of documents with ids (JSON string)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let data;
@@ -1142,11 +1272,20 @@ Options:
 // ---------------------------------------------------------------------------
 async function runDatasetDeleteDocs(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega dataset delete-docs <resource-id> <doc-ids...>
-
-Positional args:
-  resource-id   The dataset resource ID
-  doc-ids       One or more document IDs (comma-joined)`);
+        console.log(renderHelp({
+            tagline: "Delete dataset documents by id.",
+            usage: "kweaver vega dataset delete-docs <resource-id> <doc-ids...>",
+            sections: [
+                {
+                    title: "Positional args",
+                    items: [
+                        { name: "resource-id", desc: "The dataset resource ID" },
+                        { name: "doc-ids", desc: "One or more document IDs (comma-joined)" },
+                    ],
+                },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     const { remaining, businessDomain, pretty } = parseCommonFlags(args);
@@ -1173,10 +1312,14 @@ Positional args:
 // ---------------------------------------------------------------------------
 async function runDatasetDeleteDocsQuery(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega dataset delete-docs-query <resource-id> -d <filter-json>
-
-Options:
-  -d, --data <json>   Filter condition (JSON string)`);
+        console.log(renderHelp({
+            tagline: "Delete dataset documents matching a filter.",
+            usage: "kweaver vega dataset delete-docs-query <resource-id> -d <filter-json>",
+            flags: [
+                { name: "-d, --data <json>", desc: "Filter condition (JSON string)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let data;
@@ -1212,10 +1355,14 @@ Options:
 // ---------------------------------------------------------------------------
 async function runDatasetBuild(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega dataset build <resource-id> [options]
-
-Options:
-  --mode <mode>   Build mode: full, incremental, realtime (default: full)`);
+        console.log(renderHelp({
+            tagline: "Build a Vega dataset.",
+            usage: "kweaver vega dataset build <resource-id> [options]",
+            flags: [
+                { name: "--mode <mode>", desc: "Build mode: full, incremental, realtime (default: full)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let mode = "full";
@@ -1251,7 +1398,11 @@ Options:
 // ---------------------------------------------------------------------------
 async function runDatasetBuildStatus(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega dataset build-status <resource-id> <task-id>`);
+        console.log(renderHelp({
+            tagline: "Get dataset build status.",
+            usage: "kweaver vega dataset build-status <resource-id> <task-id>",
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     const { remaining, businessDomain, pretty } = parseCommonFlags(args);
@@ -1279,10 +1430,19 @@ async function runDatasetBuildStatus(args) {
 async function runVegaQueryCommand(args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "--help" || sub === "-h") {
-        console.log(`kweaver vega query
-
-Subcommands:
-  execute -d <json>   Execute a query`);
+        console.log(renderHelp({
+            tagline: "Execute structured Vega queries.",
+            usage: "kweaver vega query <subcommand> [flags]",
+            sections: [
+                {
+                    title: "AVAILABLE COMMANDS",
+                    items: [
+                        { name: "execute", desc: "Execute a structured query (-d <json>)" },
+                    ],
+                },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     if (sub === "execute")
@@ -1295,10 +1455,14 @@ Subcommands:
 // ---------------------------------------------------------------------------
 async function runQueryExecute(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega query execute -d <json>
-
-Options:
-  -d, --data <json>   Query body (tables, joins, output_fields, filter_condition, sort, limit, ...)`);
+        console.log(renderHelp({
+            tagline: "Execute a Vega query.",
+            usage: "kweaver vega query execute -d <json>",
+            flags: [
+                { name: "-d, --data <json>", desc: "Query body (tables, joins, output_fields, filter_condition, sort, limit, ...)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let data;
@@ -1329,43 +1493,59 @@ Options:
 // ---------------------------------------------------------------------------
 async function runVegaSql(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega sql --resource-type <type> --query "<sql-or-dsl>"
-kweaver vega sql -d <json>
-
-POST /api/vega-backend/v1/resources/query — execute SQL (MySQL/MariaDB/PostgreSQL) or OpenSearch DSL.
-
-Simple mode (no JSON escaping for query + type):
-  --resource-type <t>   Required with --query unless using -d
-  --query <string>      One shell argument: the full SQL (or DSL string). Always quote it.
-
-Advanced mode (full request body, optional fields):
-  -d, --data <json>     Raw JSON body. When present, this mode is used and any --query / --resource-type are ignored.
-
-Resource placeholders (how to reference Vega tables in SQL):
-  {{<resource_id>}}     Required token form: double braces around the Vega resource id (from vega resource list / get).
-  {{.<resource_id>}}    Alternate form with a dot after {{ ; same replacement and routing.
-
-  The backend swaps each placeholder for that resource's physical SourceIdentifier and picks the catalog connector.
-  Without at least one placeholder, queries often fail (e.g. connector config is incomplete) unless a default connector exists.
-
-  Shell (simple mode) — wrap the whole SQL so braces are not interpreted by the shell:
-    kweaver vega sql --resource-type mysql --query "SELECT * FROM {{abc123xyz}} LIMIT 5"
-
-  Shell (-d mode) — placeholders live inside the JSON string value; use single quotes around the JSON so inner double quotes work:
-    kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{abc123xyz}} LIMIT 5"}'
-
-Body fields (JSON / simple mode mapping):
-  query          (required) SQL string or OpenSearch DSL object
-  resource_type  (required) e.g. mysql, mariadb, postgresql, opensearch (see vega connector-type list)
-  stream_size    optional batch size for streaming (100–10000, default 10000)
-  query_timeout  optional seconds (1–3600, default 60)
-  query_id       optional cursor session id
-
-Do not use --type; use --resource-type.
-
-Common flags:
-  -bd, --biz-domain <s>   Business domain (default: bd_public)
-  --pretty               Pretty-print JSON (default)`);
+        console.log(renderHelp({
+            tagline: "POST /api/vega-backend/v1/resources/query — execute SQL (MySQL/MariaDB/PostgreSQL) or OpenSearch DSL.",
+            usage: [
+                "kweaver vega sql --resource-type <type> --query \"<sql-or-dsl>\"",
+                "kweaver vega sql -d <json>",
+            ].join("\n"),
+            sections: [
+                {
+                    title: "Simple mode (no JSON escaping for query + type)",
+                    items: [
+                        { name: "--resource-type <t>", desc: "Required with --query unless using -d" },
+                        { name: "--query <string>", desc: "One shell argument: the full SQL (or DSL string). Always quote it." },
+                    ],
+                },
+                {
+                    title: "Advanced mode (full request body, optional fields)",
+                    items: [
+                        { name: "-d, --data <json>", desc: "Raw JSON body. When present, this mode is used and any --query / --resource-type are ignored." },
+                    ],
+                },
+                {
+                    title: "Resource placeholders (how to reference Vega tables in SQL)",
+                    items: [
+                        { name: "{{<resource_id>}}", desc: "Required token form: double braces around the Vega resource id (from vega resource list / get)." },
+                        { name: "{{.<resource_id>}}", desc: "Alternate form with a dot after {{ ; same replacement and routing." },
+                    ],
+                },
+                {
+                    title: "Body fields (JSON / simple mode mapping)",
+                    items: [
+                        { name: "query", desc: "(required) SQL string or OpenSearch DSL object" },
+                        { name: "resource_type", desc: "(required) e.g. mysql, mariadb, postgresql, opensearch (see vega connector-type list)" },
+                        { name: "stream_size", desc: "optional batch size for streaming (100–10000, default 10000)" },
+                        { name: "query_timeout", desc: "optional seconds (1–3600, default 60)" },
+                        { name: "query_id", desc: "optional cursor session id" },
+                    ],
+                },
+            ],
+            flags: [
+                { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+                { name: "--pretty", desc: "Pretty-print JSON (default)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver vega sql --resource-type mysql --query \"SELECT * FROM {{abc123xyz}} LIMIT 5\"",
+                "kweaver vega sql -d '{\"resource_type\":\"mysql\",\"query\":\"SELECT * FROM {{abc123xyz}} LIMIT 5\"}'",
+            ],
+            learnMore: [
+                "The backend swaps each placeholder for that resource's physical SourceIdentifier and picks the catalog connector.",
+                "Without at least one placeholder, queries often fail (e.g. connector config is incomplete) unless a default connector exists.",
+                "Do not use --type; use --resource-type.",
+            ],
+        }));
         return 0;
     }
     let data;
@@ -1425,15 +1605,24 @@ Common flags:
 async function runVegaConnectorTypeCommand(args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "--help" || sub === "-h") {
-        console.log(`kweaver vega connector-type
-
-Subcommands:
-  list                            List connector types
-  get <type>                      Get connector type details
-  register -d <json>              Register a new connector type
-  update <type> -d <json>         Update connector type
-  delete <type> [-y]              Delete connector type
-  enable <type> --enabled <bool>  Enable/disable connector type`);
+        console.log(renderHelp({
+            tagline: "Manage Vega connector types.",
+            usage: "kweaver vega connector-type <subcommand> [flags]",
+            sections: [
+                {
+                    title: "AVAILABLE COMMANDS",
+                    items: [
+                        { name: "list", desc: "List connector types" },
+                        { name: "get", desc: "Get connector type details" },
+                        { name: "register", desc: "Register a new connector type" },
+                        { name: "update", desc: "Update connector type" },
+                        { name: "delete", desc: "Delete connector type" },
+                        { name: "enable", desc: "Enable/disable connector type" },
+                    ],
+                },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     if (sub === "list")
@@ -1456,7 +1645,11 @@ Subcommands:
 // ---------------------------------------------------------------------------
 async function runConnectorTypeList(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("kweaver vega connector-type list");
+        console.log(renderHelp({
+            tagline: "List Vega connector types.",
+            usage: "kweaver vega connector-type list",
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     const { businessDomain, pretty } = parseCommonFlags(args);
@@ -1474,7 +1667,11 @@ async function runConnectorTypeList(args) {
 // ---------------------------------------------------------------------------
 async function runConnectorTypeGet(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("kweaver vega connector-type get <type>");
+        console.log(renderHelp({
+            tagline: "Get connector type details.",
+            usage: "kweaver vega connector-type get <type>",
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     const { remaining, businessDomain, pretty } = parseCommonFlags(args);
@@ -1498,10 +1695,14 @@ async function runConnectorTypeGet(args) {
 // ---------------------------------------------------------------------------
 async function runConnectorTypeRegister(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega connector-type register -d <json>
-
-Options:
-  -d, --data <json>   Connector type definition (JSON string)`);
+        console.log(renderHelp({
+            tagline: "Register a new connector type.",
+            usage: "kweaver vega connector-type register -d <json>",
+            flags: [
+                { name: "-d, --data <json>", desc: "Connector type definition (JSON string)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let data;
@@ -1532,10 +1733,14 @@ Options:
 // ---------------------------------------------------------------------------
 async function runConnectorTypeUpdate(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega connector-type update <type> -d <json>
-
-Options:
-  -d, --data <json>   Updated fields (JSON string)`);
+        console.log(renderHelp({
+            tagline: "Update a connector type.",
+            usage: "kweaver vega connector-type update <type> -d <json>",
+            flags: [
+                { name: "-d, --data <json>", desc: "Updated fields (JSON string)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let data;
@@ -1571,10 +1776,14 @@ Options:
 // ---------------------------------------------------------------------------
 async function runConnectorTypeDelete(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega connector-type delete <type> [-y]
-
-Options:
-  -y, --yes   Skip confirmation prompt`);
+        console.log(renderHelp({
+            tagline: "Delete a connector type.",
+            usage: "kweaver vega connector-type delete <type> [-y]",
+            flags: [
+                { name: "-y, --yes", desc: "Skip confirmation prompt" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let yes = false;
@@ -1615,7 +1824,14 @@ Options:
 // ---------------------------------------------------------------------------
 async function runConnectorTypeEnable(args) {
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`kweaver vega connector-type enable <type> --enabled <true|false>`);
+        console.log(renderHelp({
+            tagline: "Enable or disable a connector type.",
+            usage: "kweaver vega connector-type enable <type> --enabled <true|false>",
+            flags: [
+                { name: "--enabled <true|false>", desc: "Whether to enable the connector type" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+        }));
         return 0;
     }
     let enabled;