dataiku-sdk 0.7.0 → 0.9.0

package/dist/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createHash, } from "node:crypto";
-import { readFileSync, } from "node:fs";
+import { readFileSync, writeFileSync, } from "node:fs";
 import { mkdir, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve, } from "node:path";
 import { fileURLToPath, } from "node:url";
@@ -1064,7 +1064,7 @@ function resolveSqlInput(args, flags) {
     }
     return query;
 }
-const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS] [--keep] [--full-log] [--project-key KEY]";
+const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS] [--keep] [--full-log] [--max-log-bytes N] [--project-key KEY]";
 function resolveCodeInput(args, flags) {
     if (args.length > 0) {
         throw new UsageError(`code run takes no positional arguments; pass the script via --file PATH or --stdin. Usage: ${CODE_RUN_USAGE}`);
@@ -1119,6 +1119,23 @@ function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
     return lines.join("\n");
 }
 let outputFieldProjection;
+/**
+ * Non-fatal diagnostics queued during a command and flushed to stderr as one
+ * JSON envelope, so agents get a loud, machine-parseable signal (e.g. truncated
+ * exports) without polluting the stdout result contract.
+ */
+let pendingCliWarnings = [];
+function enqueueCliWarning(warning) {
+    pendingCliWarnings.push(warning);
+}
+/** Emit queued warnings as a single `{ warnings: [...] }` object on stderr. Idempotent. */
+function flushCliWarnings() {
+    if (pendingCliWarnings.length === 0)
+        return;
+    const warnings = pendingCliWarnings;
+    pendingCliWarnings = [];
+    process.stderr.write(`${JSON.stringify({ warnings, }, null, 2)}\n`);
+}
 function resolveFieldPath(source, field) {
     let current = source;
     for (const segment of field.split(".")) {
@@ -1148,6 +1165,7 @@ function projectResultFields(result, fields) {
     return pickResultFields(result, fields);
 }
 function writeCommandResult(result) {
+    flushCliWarnings();
     const projected = outputFieldProjection
         ? projectResultFields(result, outputFieldProjection)
         : result;
@@ -1495,6 +1513,7 @@ const FLAG_ALIASES = {
     "extra-ca-certs": "ca-cert",
     explain: "plan",
     "zone-name": "zone",
+    rows: "max-rows",
 };
 const VALUE_FLAGS = new Set([
     "fields",
@@ -1535,6 +1554,7 @@ const VALUE_FLAGS = new Set([
     "max-edges",
     "max-lines",
     "max-log-lines",
+    "max-log-bytes",
     "listed",
     "max-nodes",
     "max-rows",
@@ -1729,6 +1749,1227 @@ const commands = {
                 "dss project map --include-raw",
             ],
         },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss project create <projectKey> <name> [--owner LOGIN] [--data JSON|--data-file PATH|--stdin]");
+                return c.projects.createProject(a[0], a[1], f["owner"], jsonInput(f));
+            },
+            usage: "dss project create <projectKey> <name> [--owner LOGIN] [--data JSON|--data-file PATH|--stdin]",
+            description: "Create a new project (optionally with owner login and settings).",
+            examples: ["dss project create MY_PROJ MyProject",],
+        },
+        delete: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project delete <projectKey> [--drop-data]");
+                await c.projects.deleteProject(a[0], f["drop-data"] === true);
+                return { deleted: a[0], };
+            },
+            usage: "dss project delete <projectKey> [--drop-data]",
+            description: "Delete a project (destructive). --drop-data also clears managed datasets.",
+            examples: ["dss project delete MY_PROJ",],
+        },
+        duplicate: {
+            handler: (c, a, f) => {
+                requireArgs(a, 3, "dss project duplicate <sourceKey> <targetKey> <targetName> [--data JSON|--data-file PATH|--stdin]");
+                return c.projects.duplicate(a[0], a[1], a[2], jsonInput(f));
+            },
+            usage: "dss project duplicate <sourceKey> <targetKey> <targetName> [--data JSON|--data-file PATH|--stdin]",
+            description: "Duplicate a project into a new project key.",
+            examples: ["dss project duplicate SRC NEW NewProject",],
+        },
+        export: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project export <projectKey> --output PATH [--data JSON|--data-file PATH|--stdin]");
+                const out = f["output"];
+                if (!out)
+                    throw new UsageError("--output PATH is required.", "missing_required_flag");
+                await c.projects.exportArchive(a[0], out, jsonInput(f));
+                return { path: out, };
+            },
+            usage: "dss project export <projectKey> --output PATH [--data JSON|--data-file PATH|--stdin]",
+            description: "Export a project to a local archive (.zip).",
+            examples: ["dss project export MY_PROJ --output ./my_proj.zip",],
+        },
+        import: {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss project import <filePath>");
+                return c.projects.importProjectFromArchive(a[0]);
+            },
+            usage: "dss project import <filePath>",
+            description: "Upload a project archive to prepare an import (returns a temporary import id).",
+            examples: ["dss project import ./my_proj.zip",],
+        },
+        "permissions-get": {
+            handler: (c, _a, f) => c.projects.getPermissions(f["project-key"]),
+            usage: "dss project permissions-get [--project-key KEY]",
+            description: "Get a project's permissions.",
+            examples: ["dss project permissions-get --project-key MY_PROJ",],
+        },
+        "permissions-set": {
+            handler: async (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (permissions object).");
+                await c.projects.setPermissions(f["project-key"], body);
+                return { updated: true, };
+            },
+            usage: "dss project permissions-set (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a project's permissions.",
+            examples: ["dss project permissions-set --data-file perms.json --project-key MY_PROJ",],
+        },
+        "settings-get": {
+            handler: (c, _a, f) => c.projects.getSettings(f["project-key"]),
+            usage: "dss project settings-get [--project-key KEY]",
+            description: "Get a project's settings.",
+            examples: ["dss project settings-get --project-key MY_PROJ",],
+        },
+        "settings-set": {
+            handler: async (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (settings object).");
+                await c.projects.setSettings(f["project-key"], body);
+                return { updated: true, };
+            },
+            usage: "dss project settings-set (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a project's settings.",
+            examples: ["dss project settings-set --data-file settings.json --project-key MY_PROJ",],
+        },
+    },
+    app: {
+        list: {
+            handler: (c) => c.applications.listApps(),
+            usage: "dss app list",
+            description: "List all Dataiku App templates.",
+            examples: ["dss app list",],
+        },
+        manifest: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss app manifest <appId>");
+                return c.applications.getAppManifest(a[0]);
+            },
+            usage: "dss app manifest <appId>",
+            description: "Get the manifest of a Dataiku App template.",
+            examples: ["dss app manifest my-app",],
+        },
+        instances: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss app instances <appId>");
+                return c.applications.listInstances(a[0]);
+            },
+            usage: "dss app instances <appId>",
+            description: "List instances created from a Dataiku App template.",
+            examples: ["dss app instances my-app",],
+        },
+        "create-instance": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss app create-instance <appId> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (instance creation payload).");
+                return c.applications.createInstance(a[0], body);
+            },
+            usage: "dss app create-instance <appId> (--data JSON|--data-file PATH|--stdin)",
+            description: "Create an app instance from a Dataiku App template.",
+            examples: ['dss app create-instance my-app --data \'{"targetProjectKey":"NEWPROJ"}\'',],
+        },
+        "instance-manifest": {
+            handler: (c, _a, f) => c.applications.getInstanceManifest(f["project-key"]),
+            usage: "dss app instance-manifest [--project-key KEY]",
+            description: "Get the app manifest of an app-instance project.",
+            examples: ["dss app instance-manifest --project-key MYINSTANCE",],
+        },
+        "save-instance-manifest": {
+            handler: (c, _a, f) => {
+                const manifest = requiredJsonInput(f, "--data, --data-file, or --stdin is required (manifest JSON).");
+                return c.applications.saveInstanceManifest(manifest, f["project-key"]);
+            },
+            usage: "dss app save-instance-manifest (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Save the app manifest of an app-instance project (homepage sections, use-as-recipe settings).",
+            examples: ["dss app save-instance-manifest --data-file manifest.json --project-key MYINSTANCE",],
+        },
+        "delete-instance": {
+            handler: async (c, _a, f) => {
+                await c.applications.deleteInstance(f["project-key"]);
+                return { deleted: true, };
+            },
+            usage: "dss app delete-instance [--project-key KEY]",
+            description: "Delete an app-instance project (destructive: removes the instance project).",
+            examples: ["dss app delete-instance --project-key MYINSTANCE",],
+        },
+        "business-app-instance-permissions": {
+            handler: (c, a) => {
+                requireArgs(a, 3, "dss app business-app-instance-permissions <businessAppId> <instanceProjectKey> <userLogin>");
+                return c.applications.getBusinessAppInstanceUserPermissions(a[0], a[1], a[2]);
+            },
+            usage: "dss app business-app-instance-permissions <businessAppId> <instanceProjectKey> <userLogin>",
+            description: "Get a user's effective permissions on a Business App instance.",
+            examples: ["dss app business-app-instance-permissions my-bapp INSTANCEPROJ alice",],
+        },
+    },
+    "business-app": {
+        list: {
+            handler: (c) => c.applications.listBusinessApps(),
+            usage: "dss business-app list",
+            description: "List all Business Apps.",
+            examples: ["dss business-app list",],
+        },
+        get: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss business-app get <id>");
+                return c.applications.getBusinessApp(a[0]);
+            },
+            usage: "dss business-app get <id>",
+            description: "Get Business App details.",
+            examples: ["dss business-app get my-bapp",],
+        },
+        settings: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss business-app settings <id>");
+                return c.applications.getBusinessAppSettings(a[0]);
+            },
+            usage: "dss business-app settings <id>",
+            description: "Get Business App settings.",
+            examples: ["dss business-app settings my-bapp",],
+        },
+        "save-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss business-app save-settings <id> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (settings JSON).");
+                return c.applications.saveBusinessAppSettings(a[0], body);
+            },
+            usage: "dss business-app save-settings <id> (--data JSON|--data-file PATH|--stdin)",
+            description: "Save Business App settings (admin only; includes connection remapping).",
+            examples: ["dss business-app save-settings my-bapp --data-file settings.json",],
+        },
+        instances: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss business-app instances <id>");
+                return c.applications.listBusinessAppInstances(a[0]);
+            },
+            usage: "dss business-app instances <id>",
+            description: "List instances of a Business App.",
+            examples: ["dss business-app instances my-bapp",],
+        },
+        "create-instance": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss business-app create-instance <id> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (instance payload).");
+                return c.applications.createBusinessAppInstance(a[0], body);
+            },
+            usage: "dss business-app create-instance <id> (--data JSON|--data-file PATH|--stdin)",
+            description: "Create an instance of a Business App.",
+            examples: ["dss business-app create-instance my-bapp --data '{}'",],
+        },
+        "upgrade-instance": {
+            handler: (c, a) => {
+                requireArgs(a, 2, "dss business-app upgrade-instance <id> <projectKey>");
+                return c.applications.upgradeBusinessAppInstance(a[0], a[1]);
+            },
+            usage: "dss business-app upgrade-instance <id> <projectKey>",
+            description: "Upgrade a Business App instance to the latest version.",
+            examples: ["dss business-app upgrade-instance my-bapp INSTANCEPROJ",],
+        },
+        "install-from-archive": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss business-app install-from-archive <filePath>");
+                await c.applications.installBusinessAppFromArchive(a[0]);
+                return { installed: true, };
+            },
+            usage: "dss business-app install-from-archive <filePath>",
+            description: "Install or upgrade a Business App from a zip archive (admin only).",
+            examples: ["dss business-app install-from-archive ./my-bapp.zip",],
+        },
+    },
+    webapp: {
+        list: {
+            handler: (c, _a, f) => c.webapps.list(f["project-key"]),
+            usage: "dss webapp list [--project-key KEY]",
+            description: "List webapps in a project.",
+            examples: ["dss webapp list",],
+        },
+        "get-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss webapp get-settings <webappId> [--project-key KEY]");
+                return c.webapps.getSettings(a[0], f["project-key"]);
+            },
+            usage: "dss webapp get-settings <webappId> [--project-key KEY]",
+            description: "Get a webapp's settings.",
+            examples: ["dss webapp get-settings WEBAPP_ID",],
+        },
+        create: {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (webapp definition).");
+                return c.webapps.create(body, f["project-key"]);
+            },
+            usage: "dss webapp create (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Create a webapp from a JSON definition.",
+            examples: ["dss webapp create --data-file webapp.json",],
+        },
+        "update-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (webapp settings).");
+                return c.webapps.updateSettings(a[0], body, f["project-key"]);
+            },
+            usage: "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a webapp's settings.",
+            examples: ["dss webapp update-settings WEBAPP_ID --data-file webapp.json",],
+        },
+        "stop-backend": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss webapp stop-backend <webappId> [--project-key KEY]");
+                await c.webapps.stopBackend(a[0], f["project-key"]);
+                return { stopped: true, };
+            },
+            usage: "dss webapp stop-backend <webappId> [--project-key KEY]",
+            description: "Stop a webapp's backend.",
+            examples: ["dss webapp stop-backend WEBAPP_ID",],
+        },
+        "restart-backend": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss webapp restart-backend <webappId> [--project-key KEY]");
+                await c.webapps.startOrRestartBackend(a[0], f["project-key"]);
+                return { restarted: true, };
+            },
+            usage: "dss webapp restart-backend <webappId> [--project-key KEY]",
+            description: "Start or restart a webapp's backend.",
+            examples: ["dss webapp restart-backend WEBAPP_ID",],
+        },
+        "backend-state": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss webapp backend-state <webappId> [--project-key KEY]");
+                return c.webapps.getBackendState(a[0], f["project-key"]);
+            },
+            usage: "dss webapp backend-state <webappId> [--project-key KEY]",
+            description: "Get a webapp backend's runtime state.",
+            examples: ["dss webapp backend-state WEBAPP_ID",],
+        },
+    },
+    "api-service": {
+        list: {
+            handler: (c, _a, f) => c.apiServices.list(f["project-key"]),
+            usage: "dss api-service list [--project-key KEY]",
+            description: "List API services in a project.",
+            examples: ["dss api-service list",],
+        },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss api-service create <serviceId> [--project-key KEY]");
+                return c.apiServices.create(a[0], f["project-key"]);
+            },
+            usage: "dss api-service create <serviceId> [--project-key KEY]",
+            description: "Create an empty API service.",
+            examples: ["dss api-service create my-service",],
+        },
+        "get-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss api-service get-settings <serviceId> [--project-key KEY]");
+                return c.apiServices.getSettings(a[0], f["project-key"]);
+            },
+            usage: "dss api-service get-settings <serviceId> [--project-key KEY]",
+            description: "Get an API service's settings (endpoint definitions).",
+            examples: ["dss api-service get-settings my-service",],
+        },
+        "save-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (service settings).");
+                return c.apiServices.saveSettings(a[0], body, f["project-key"]);
+            },
+            usage: "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Save an API service's settings.",
+            examples: ["dss api-service save-settings my-service --data-file service.json",],
+        },
+        "list-packages": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss api-service list-packages <serviceId> [--project-key KEY]");
+                return c.apiServices.listPackages(a[0], f["project-key"]);
+            },
+            usage: "dss api-service list-packages <serviceId> [--project-key KEY]",
+            description: "List deployable packages of an API service.",
+            examples: ["dss api-service list-packages my-service",],
+        },
+        "package-summary": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss api-service package-summary <serviceId> <packageId> [--project-key KEY]");
+                return c.apiServices.getPackageSummary(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss api-service package-summary <serviceId> <packageId> [--project-key KEY]",
+            description: "Get a package summary.",
+            examples: ["dss api-service package-summary my-service v1",],
+        },
+        "create-package": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss api-service create-package <serviceId> <packageId> [--project-key KEY]");
+                return c.apiServices.createPackage(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss api-service create-package <serviceId> <packageId> [--project-key KEY]",
+            description: "Build a deployable package from the current service state.",
+            examples: ["dss api-service create-package my-service v1",],
+        },
+        "delete-package": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss api-service delete-package <serviceId> <packageId> [--project-key KEY]");
+                await c.apiServices.deletePackage(a[0], a[1], f["project-key"]);
+                return { deleted: true, };
+            },
+            usage: "dss api-service delete-package <serviceId> <packageId> [--project-key KEY]",
+            description: "Delete an API service package.",
+            examples: ["dss api-service delete-package my-service v1",],
+        },
+        "download-package": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss api-service download-package <serviceId> <packageId> --output PATH [--project-key KEY]");
+                const out = f["output"];
+                if (!out)
+                    throw new UsageError("--output PATH is required.", "missing_required_flag");
+                const res = await c.apiServices.downloadPackageArchive(a[0], a[1], f["project-key"]);
+                const buf = Buffer.from(await res.arrayBuffer());
+                writeFileSync(out, buf);
+                return { path: out, bytes: buf.length, };
+            },
+            usage: "dss api-service download-package <serviceId> <packageId> --output PATH [--project-key KEY]",
+            description: "Download an API service package archive to a local file.",
+            examples: ["dss api-service download-package my-service v1 --output ./pkg.zip",],
+        },
+        "publish-package": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss api-service publish-package <serviceId> <packageId> [--project-key KEY]");
+                return c.apiServices.publishPackage(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss api-service publish-package <serviceId> <packageId> [--project-key KEY]",
+            description: "Publish a package to the API Deployer.",
+            examples: ["dss api-service publish-package my-service v1",],
+        },
+    },
+    "api-deployer": {
+        "list-infras": {
+            handler: (c) => c.apiDeployer.listInfras(),
+            usage: "dss api-deployer list-infras",
+            description: "List API Deployer infrastructures.",
+            examples: ["dss api-deployer list-infras",],
+        },
+        "create-infra": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (infra settings).");
+                return c.apiDeployer.createInfra(body);
+            },
+            usage: "dss api-deployer create-infra (--data JSON|--data-file PATH|--stdin)",
+            description: "Create an API Deployer infrastructure.",
+            examples: ["dss api-deployer create-infra --data-file infra.json",],
+        },
+        "get-infra": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer get-infra <infraId>");
+                return c.apiDeployer.getInfra(a[0]);
+            },
+            usage: "dss api-deployer get-infra <infraId>",
+            description: "Get an API Deployer infrastructure status.",
+            examples: ["dss api-deployer get-infra prod-infra",],
+        },
+        "delete-infra": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss api-deployer delete-infra <infraId>");
+                await c.apiDeployer.deleteInfra(a[0]);
+                return { deleted: true, };
+            },
+            usage: "dss api-deployer delete-infra <infraId>",
+            description: "Delete an API Deployer infrastructure.",
+            examples: ["dss api-deployer delete-infra prod-infra",],
+        },
+        "list-stages": {
+            handler: (c) => c.apiDeployer.listStages(),
+            usage: "dss api-deployer list-stages",
+            description: "List API Deployer lifecycle stages.",
+            examples: ["dss api-deployer list-stages",],
+        },
+        "list-services": {
+            handler: (c) => c.apiDeployer.listServices(),
+            usage: "dss api-deployer list-services",
+            description: "List published API Deployer services.",
+            examples: ["dss api-deployer list-services",],
+        },
+        "create-service": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (service definition).");
+                return c.apiDeployer.createService(body);
+            },
+            usage: "dss api-deployer create-service (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a published API Deployer service.",
+            examples: ['dss api-deployer create-service --data \'{"id":"my-service"}\'',],
+        },
+        "get-service": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer get-service <serviceId>");
+                return c.apiDeployer.getService(a[0]);
+            },
+            usage: "dss api-deployer get-service <serviceId>",
+            description: "Get a published service's status (versions + deployments).",
+            examples: ["dss api-deployer get-service my-service",],
+        },
+        "delete-service": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss api-deployer delete-service <serviceId>");
+                await c.apiDeployer.deleteService(a[0]);
+                return { deleted: true, };
+            },
+            usage: "dss api-deployer delete-service <serviceId>",
+            description: "Delete a published API Deployer service.",
+            examples: ["dss api-deployer delete-service my-service",],
+        },
+        "publish-version": {
+            handler: async (c, a) => {
+                requireArgs(a, 2, "dss api-deployer publish-version <serviceId> <archive.zip>");
+                await c.apiDeployer.publishServiceVersion(a[0], a[1]);
+                return { published: true, };
+            },
+            usage: "dss api-deployer publish-version <serviceId> <archive.zip>",
+            description: "Publish (upload) a service version package to the API Deployer.",
+            examples: ["dss api-deployer publish-version my-service ./pkg.zip",],
+        },
+        "delete-version": {
+            handler: async (c, a) => {
+                requireArgs(a, 2, "dss api-deployer delete-version <serviceId> <version>");
+                await c.apiDeployer.deleteServiceVersion(a[0], a[1]);
+                return { deleted: true, };
+            },
+            usage: "dss api-deployer delete-version <serviceId> <version>",
+            description: "Delete a published service version.",
+            examples: ["dss api-deployer delete-version my-service v1",],
+        },
+        "list-deployments": {
+            handler: (c) => c.apiDeployer.listDeployments(),
+            usage: "dss api-deployer list-deployments",
+            description: "List API Deployer deployments.",
+            examples: ["dss api-deployer list-deployments",],
+        },
+        "create-deployment": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (deployment settings).");
+                return c.apiDeployer.createDeployment(body);
+            },
+            usage: "dss api-deployer create-deployment (--data JSON|--data-file PATH|--stdin)",
+            description: "Create an API Deployer deployment (maps a service version to an infra).",
+            examples: ["dss api-deployer create-deployment --data-file deployment.json",],
+        },
+        "get-deployment": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer get-deployment <deploymentId>");
+                return c.apiDeployer.getDeployment(a[0]);
+            },
+            usage: "dss api-deployer get-deployment <deploymentId>",
+            description: "Get an API Deployer deployment.",
+            examples: ["dss api-deployer get-deployment my-deployment",],
+        },
+        "deployment-status": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer deployment-status <deploymentId>");
+                return c.apiDeployer.getDeploymentStatus(a[0]);
+            },
+            usage: "dss api-deployer deployment-status <deploymentId>",
+            description: "Get an API Deployer deployment's full health/status.",
+            examples: ["dss api-deployer deployment-status my-deployment",],
+        },
+        "deployment-settings": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer deployment-settings <deploymentId>");
+                return c.apiDeployer.getDeploymentSettings(a[0]);
+            },
+            usage: "dss api-deployer deployment-settings <deploymentId>",
+            description: "Get an API Deployer deployment's settings.",
+            examples: ["dss api-deployer deployment-settings my-deployment",],
+        },
+        "save-deployment-settings": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss api-deployer save-deployment-settings <deploymentId> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (deployment settings).");
+                await c.apiDeployer.saveDeploymentSettings(a[0], body);
+                return { saved: true, };
+            },
+            usage: "dss api-deployer save-deployment-settings <deploymentId> (--data JSON|--data-file PATH|--stdin)",
+            description: "Save an API Deployer deployment's settings.",
+            examples: ["dss api-deployer save-deployment-settings my-deployment --data-file settings.json",],
+        },
+        deploy: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer deploy <deploymentId>");
+                return c.apiDeployer.startDeploymentUpdate(a[0]);
+            },
+            usage: "dss api-deployer deploy <deploymentId>",
+            description: "Apply a deployment's settings to its infrastructure (start update).",
+            examples: ["dss api-deployer deploy my-deployment",],
+        },
+        "delete-deployment": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss api-deployer delete-deployment <deploymentId>");
+                await c.apiDeployer.deleteDeployment(a[0]);
+                return { deleted: true, };
+            },
+            usage: "dss api-deployer delete-deployment <deploymentId>",
+            description: "Delete an API Deployer deployment.",
+            examples: ["dss api-deployer delete-deployment my-deployment",],
+        },
+    },
+    bundle: {
+        "list-exported": {
+            handler: (c, _a, f) => c.bundles.listExported(f["project-key"]),
+            usage: "dss bundle list-exported [--project-key KEY]",
+            description: "List bundles exported from a project on the Design node.",
+            examples: ["dss bundle list-exported",],
+        },
+        export: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle export <bundleId> [--project-key KEY]");
+                await c.bundles.exportBundle(a[0], f["project-key"]);
+                return { exported: a[0], };
+            },
+            usage: "dss bundle export <bundleId> [--project-key KEY]",
+            description: "Create (or overwrite) an exported Design-node bundle.",
+            examples: ["dss bundle export v1",],
+        },
+        "delete-exported": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle delete-exported <bundleId> [--project-key KEY]");
+                await c.bundles.deleteExported(a[0], f["project-key"]);
+                return { deleted: true, };
+            },
+            usage: "dss bundle delete-exported <bundleId> [--project-key KEY]",
+            description: "Delete an exported Design-node bundle.",
+            examples: ["dss bundle delete-exported v1",],
+        },
+        "download-exported": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle download-exported <bundleId> --output PATH [--project-key KEY]");
+                const out = f["output"];
+                if (!out)
+                    throw new UsageError("--output PATH is required.", "missing_required_flag");
+                const res = await c.bundles.downloadExportedArchive(a[0], f["project-key"]);
+                const buf = Buffer.from(await res.arrayBuffer());
+                writeFileSync(out, buf);
+                return { path: out, bytes: buf.length, };
+            },
+            usage: "dss bundle download-exported <bundleId> --output PATH [--project-key KEY]",
+            description: "Download an exported Design-node bundle archive to a local file.",
+            examples: ["dss bundle download-exported v1 --output ./bundle.zip",],
+        },
+        publish: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss bundle publish <bundleId> [--project-key KEY]");
+                return c.bundles.publish(a[0], f["project-key"]);
+            },
+            usage: "dss bundle publish <bundleId> [--project-key KEY]",
+            description: "Publish a Design-node bundle to the Project Deployer.",
+            examples: ["dss bundle publish v1",],
+        },
+        "list-imported": {
+            handler: (c, _a, f) => c.bundles.listImported(f["project-key"]),
+            usage: "dss bundle list-imported [--project-key KEY]",
+            description: "List bundles imported into a project on the Automation node.",
+            examples: ["dss bundle list-imported",],
+        },
+        "import-from-archive": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss bundle import-from-archive <serverArchivePath> [--project-key KEY]");
+                return c.bundles.importFromArchive(a[0], f["project-key"]);
+            },
+            usage: "dss bundle import-from-archive <serverArchivePath> [--project-key KEY]",
+            description: "Import a server-side bundle archive into an Automation-node project.",
+            examples: ["dss bundle import-from-archive /data/bundles/v1.zip",],
+        },
+        "import-from-stream": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle import-from-stream <filePath> [--project-key KEY]");
+                await c.bundles.importFromStream(a[0], f["project-key"]);
+                return { imported: true, };
+            },
+            usage: "dss bundle import-from-stream <filePath> [--project-key KEY]",
+            description: "Upload and import a local bundle archive into an Automation-node project.",
+            examples: ["dss bundle import-from-stream ./v1.zip",],
+        },
+        activate: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss bundle activate <bundleId> [--project-key KEY]");
+                return c.bundles.activate(a[0], f["project-key"]);
+            },
+            usage: "dss bundle activate <bundleId> [--project-key KEY]",
+            description: "Activate an imported Automation-node bundle.",
+            examples: ["dss bundle activate v1",],
+        },
+        preload: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss bundle preload <bundleId> [--project-key KEY]");
+                return c.bundles.preload(a[0], f["project-key"]);
+            },
+            usage: "dss bundle preload <bundleId> [--project-key KEY]",
+            description: "Preload an imported Automation-node bundle (stage data/models).",
+            examples: ["dss bundle preload v1",],
+        },
+        "delete-imported": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle delete-imported <bundleId> [--project-key KEY]");
+                await c.bundles.deleteImported(a[0], f["project-key"]);
+                return { deleted: true, };
+            },
+            usage: "dss bundle delete-imported <bundleId> [--project-key KEY]",
+            description: "Delete an imported Automation-node bundle.",
+            examples: ["dss bundle delete-imported v1",],
+        },
+    },
+    "project-deployer": {
+        "list-projects": {
+            handler: (c) => c.projectDeployer.listProjects(),
+            usage: "dss project-deployer list-projects",
+            description: "List published projects on the Project Deployer.",
+            examples: ["dss project-deployer list-projects",],
+        },
+        "create-project": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (published project settings).");
+                return c.projectDeployer.createProject(body);
+            },
+            usage: "dss project-deployer create-project (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a published project on the Project Deployer.",
+            examples: ["dss project-deployer create-project --data-file project.json",],
+        },
+        "upload-bundle": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss project-deployer upload-bundle <filePath>");
+                await c.projectDeployer.uploadBundle(a[0]);
+                return { uploaded: true, };
+            },
+            usage: "dss project-deployer upload-bundle <filePath>",
+            description: "Upload a project bundle archive to the Project Deployer.",
+            examples: ["dss project-deployer upload-bundle ./v1.zip",],
+        },
+        "project-status": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss project-deployer project-status <publishedProjectKey>");
+                return c.projectDeployer.getProjectStatus(a[0]);
+            },
+            usage: "dss project-deployer project-status <publishedProjectKey>",
+            description: "Get a published project's status and available bundles.",
+            examples: ["dss project-deployer project-status MYPROJ",],
+        },
+        "list-deployments": {
+            handler: (c) => c.projectDeployer.listDeployments(),
+            usage: "dss project-deployer list-deployments",
+            description: "List Project Deployer deployments.",
+            examples: ["dss project-deployer list-deployments",],
+        },
+        "create-deployment": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (deployment settings).");
+                return c.projectDeployer.createDeployment(body);
+            },
+            usage: "dss project-deployer create-deployment (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a Project Deployer deployment (bundle to infra mapping).",
+            examples: ["dss project-deployer create-deployment --data-file deployment.json",],
+        },
+        "get-deployment": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss project-deployer get-deployment <deploymentId>");
+                return c.projectDeployer.getDeployment(a[0]);
+            },
+            usage: "dss project-deployer get-deployment <deploymentId>",
+            description: "Get a Project Deployer deployment.",
+            examples: ["dss project-deployer get-deployment my-deployment",],
+        },
+        "deployment-status": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss project-deployer deployment-status <deploymentId>");
+                return c.projectDeployer.getDeploymentStatus(a[0]);
+            },
+            usage: "dss project-deployer deployment-status <deploymentId>",
+            description: "Get a Project Deployer deployment's full health/status.",
+            examples: ["dss project-deployer deployment-status my-deployment",],
+        },
+        "save-deployment-settings": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-deployer save-deployment-settings <deploymentId> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (deployment settings).");
+                await c.projectDeployer.saveDeploymentSettings(a[0], body);
+                return { saved: true, };
+            },
+            usage: "dss project-deployer save-deployment-settings <deploymentId> (--data JSON|--data-file PATH|--stdin)",
+            description: "Save a Project Deployer deployment's settings (e.g. bundleId).",
+            examples: [
+                "dss project-deployer save-deployment-settings my-deployment --data-file settings.json",
+            ],
+        },
+        deploy: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss project-deployer deploy <deploymentId>");
+                return c.projectDeployer.startUpdate(a[0]);
+            },
+            usage: "dss project-deployer deploy <deploymentId>",
+            description: "Apply a deployment to the Automation node (start update).",
+            examples: ["dss project-deployer deploy my-deployment",],
+        },
+        "delete-deployment": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss project-deployer delete-deployment <deploymentId>");
+                await c.projectDeployer.deleteDeployment(a[0]);
+                return { deleted: true, };
+            },
+            usage: "dss project-deployer delete-deployment <deploymentId>",
+            description: "Delete a Project Deployer deployment.",
+            examples: ["dss project-deployer delete-deployment my-deployment",],
+        },
+        "list-infras": {
+            handler: (c) => c.projectDeployer.listInfras(),
+            usage: "dss project-deployer list-infras",
+            description: "List Project Deployer infrastructures.",
+            examples: ["dss project-deployer list-infras",],
+        },
+        "create-infra": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (infra settings).");
+                return c.projectDeployer.createInfra(body);
+            },
+            usage: "dss project-deployer create-infra (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a Project Deployer infrastructure.",
+            examples: ["dss project-deployer create-infra --data-file infra.json",],
+        },
+    },
+    "project-library": {
+        list: {
+            handler: (c, _a, f) => c.projectLibrary.listContents(f["project-key"]),
+            usage: "dss project-library list [--project-key KEY]",
+            description: "List the project code library (lib/) contents.",
+            examples: ["dss project-library list",],
+        },
+        get: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss project-library get <path> [--project-key KEY]");
+                return c.projectLibrary.getFile(a[0], f["project-key"]);
+            },
+            usage: "dss project-library get <path> [--project-key KEY]",
+            description: "Print the text content of a project library file.",
+            examples: ["dss project-library get python/mylib/utils.py",],
+        },
+        "get-bytes": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library get-bytes <path> --output PATH [--project-key KEY]");
+                const out = f["output"];
+                if (!out)
+                    throw new UsageError("--output PATH is required.", "missing_required_flag");
+                const bytes = await c.projectLibrary.getFileBytes(a[0], f["project-key"]);
+                writeFileSync(out, bytes);
+                return { path: out, bytes: bytes.length, };
+            },
+            usage: "dss project-library get-bytes <path> --output PATH [--project-key KEY]",
+            description: "Download a project library file's raw bytes to a local file.",
+            examples: ["dss project-library get-bytes static/logo.png --output ./logo.png",],
+        },
+        "create-file": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library create-file <path> [--project-key KEY]");
+                await c.projectLibrary.addFile(a[0], f["project-key"]);
+                return { created: a[0], };
+            },
+            usage: "dss project-library create-file <path> [--project-key KEY]",
+            description: "Create an empty file in the project library.",
+            examples: ["dss project-library create-file python/mylib/new.py",],
+        },
+        "create-folder": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library create-folder <path> [--project-key KEY]");
+                await c.projectLibrary.addFolder(a[0], f["project-key"]);
+                return { created: a[0], };
+            },
+            usage: "dss project-library create-folder <path> [--project-key KEY]",
+            description: "Create a folder in the project library.",
+            examples: ["dss project-library create-folder python/mylib",],
+        },
+        put: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--project-key KEY]");
+                const content = typeof f["content"] === "string"
+                    ? f["content"]
+                    : typeof f["file"] === "string"
+                        ? readFileSync(f["file"], "utf-8")
+                        : await readStdinText();
+                await c.projectLibrary.addOrUpdateFile(a[0], content, f["project-key"]);
+                return { updated: a[0], };
+            },
+            usage: "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--project-key KEY]",
+            description: "Create or overwrite a project library file with raw text content.",
+            examples: ["dss project-library put python/mylib/utils.py --file ./utils.py",],
+        },
+        delete: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library delete <path> [--project-key KEY]");
+                await c.projectLibrary.deleteFile(a[0], f["project-key"]);
+                return { deleted: a[0], };
+            },
+            usage: "dss project-library delete <path> [--project-key KEY]",
+            description: "Delete a project library file or folder.",
+            examples: ["dss project-library delete python/mylib/old.py",],
+        },
+        rename: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss project-library rename <path> <new-name> [--project-key KEY]");
+                await c.projectLibrary.rename(a[0], a[1], f["project-key"]);
+                return { renamed: a[0], to: a[1], };
+            },
+            usage: "dss project-library rename <path> <new-name> [--project-key KEY]",
+            description: "Rename a project library file or folder within its parent.",
+            examples: ["dss project-library rename python/mylib/old.py new.py",],
+        },
+        move: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss project-library move <path> <destination-folder> [--project-key KEY]");
+                await c.projectLibrary.move(a[0], a[1], f["project-key"]);
+                return { moved: a[0], to: a[1], };
+            },
+            usage: "dss project-library move <path> <destination-folder> [--project-key KEY]",
+            description: "Move a project library file or folder into another folder.",
+            examples: ["dss project-library move python/old.py python/mylib",],
+        },
+    },
+    "streaming-endpoint": {
+        list: {
+            handler: (c, _a, f) => c.streamingEndpoints.list(f["project-key"]),
+            usage: "dss streaming-endpoint list [--project-key KEY]",
+            description: "List streaming endpoints in a project.",
+            examples: ["dss streaming-endpoint list",],
+        },
+        get: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss streaming-endpoint get <id> [--project-key KEY]");
+                return c.streamingEndpoints.getSettings(a[0], f["project-key"]);
+            },
+            usage: "dss streaming-endpoint get <id> [--project-key KEY]",
+            description: "Get a streaming endpoint's settings.",
+            examples: ["dss streaming-endpoint get my-stream",],
+        },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss streaming-endpoint create <id> <type> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]");
+                const body = jsonInput(f) ?? {};
+                return c.streamingEndpoints.create(a[0], a[1], body, f["project-key"]);
+            },
+            usage: "dss streaming-endpoint create <id> <type> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]",
+            description: "Create a streaming endpoint of the given type.",
+            examples: ["dss streaming-endpoint create my-stream kafka",],
+        },
+        "update-settings": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss streaming-endpoint update-settings <id> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (endpoint settings).");
+                await c.streamingEndpoints.updateSettings(a[0], body, f["project-key"]);
+                return { updated: a[0], };
+            },
+            usage: "dss streaming-endpoint update-settings <id> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a streaming endpoint's settings.",
+            examples: ["dss streaming-endpoint update-settings my-stream --data-file settings.json",],
+        },
+        delete: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss streaming-endpoint delete <id> [--project-key KEY]");
+                await c.streamingEndpoints.delete(a[0], f["project-key"]);
+                return { deleted: a[0], };
+            },
+            usage: "dss streaming-endpoint delete <id> [--project-key KEY]",
+            description: "Delete a streaming endpoint.",
+            examples: ["dss streaming-endpoint delete my-stream",],
+        },
+    },
+    "continuous-activity": {
+        list: {
+            handler: (c, _a, f) => c.continuousActivities.list(f["project-key"]),
+            usage: "dss continuous-activity list [--project-key KEY]",
+            description: "List continuous activities in a project.",
+            examples: ["dss continuous-activity list",],
+        },
+        status: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss continuous-activity status <recipeId> [--project-key KEY]");
+                return c.continuousActivities.getStatus(a[0], f["project-key"]);
+            },
+            usage: "dss continuous-activity status <recipeId> [--project-key KEY]",
+            description: "Get a continuous recipe's desired and effective state.",
+            examples: ["dss continuous-activity status compute_stream",],
+        },
+        start: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss continuous-activity start <recipeId> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]");
+                return c.continuousActivities.start(a[0], jsonInput(f), f["project-key"]);
+            },
+            usage: "dss continuous-activity start <recipeId> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]",
+            description: "Start a continuous recipe (optional loop restart params via JSON).",
+            examples: ["dss continuous-activity start compute_stream",],
+        },
+        stop: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss continuous-activity stop <recipeId> [--project-key KEY]");
+                await c.continuousActivities.stop(a[0], f["project-key"]);
+                return { stopped: a[0], };
+            },
+            usage: "dss continuous-activity stop <recipeId> [--project-key KEY]",
+            description: "Stop a continuous recipe.",
+            examples: ["dss continuous-activity stop compute_stream",],
+        },
+    },
+    statistics: {
+        "list-worksheets": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss statistics list-worksheets <dataset> [--project-key KEY]");
+                return c.statistics.listWorksheets(a[0], f["project-key"]);
+            },
+            usage: "dss statistics list-worksheets <dataset> [--project-key KEY]",
+            description: "List EDA statistics worksheets for a dataset.",
+            examples: ["dss statistics list-worksheets customers",],
+        },
+        "get-worksheet": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics get-worksheet <dataset> <worksheetId> [--project-key KEY]");
+                return c.statistics.getWorksheet(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss statistics get-worksheet <dataset> <worksheetId> [--project-key KEY]",
+            description: "Get one statistics worksheet definition.",
+            examples: ["dss statistics get-worksheet customers ws_1",],
+        },
+        "create-worksheet": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss statistics create-worksheet <dataset> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
+                return c.statistics.createWorksheet(a[0], body, f["project-key"]);
+            },
+            usage: "dss statistics create-worksheet <dataset> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Create a statistics worksheet from a JSON definition.",
+            examples: ["dss statistics create-worksheet customers --data-file ws.json",],
+        },
+        "update-worksheet": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics update-worksheet <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
+                return c.statistics.updateWorksheet(a[0], a[1], body, f["project-key"]);
+            },
+            usage: "dss statistics update-worksheet <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a statistics worksheet definition.",
+            examples: ["dss statistics update-worksheet customers ws_1 --data-file ws.json",],
+        },
+        "delete-worksheet": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss statistics delete-worksheet <dataset> <worksheetId> [--project-key KEY]");
+                await c.statistics.deleteWorksheet(a[0], a[1], f["project-key"]);
+                return { deleted: a[1], };
+            },
+            usage: "dss statistics delete-worksheet <dataset> <worksheetId> [--project-key KEY]",
+            description: "Delete a statistics worksheet.",
+            examples: ["dss statistics delete-worksheet customers ws_1",],
+        },
+        "run-worksheet": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics run-worksheet <dataset> <worksheetId> [--project-key KEY]");
+                return c.statistics.runWorksheet(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss statistics run-worksheet <dataset> <worksheetId> [--project-key KEY]",
+            description: "Run a statistics worksheet and return the DSS future response.",
+            examples: ["dss statistics run-worksheet customers ws_1",],
+        },
+        "run-card": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics run-card <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const card = requiredJsonInput(f, "--data, --data-file, or --stdin is required (card settings).");
+                return c.statistics.runCard(a[0], a[1], card, f["project-key"]);
+            },
+            usage: "dss statistics run-card <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Run a single card in a worksheet context.",
+            examples: ["dss statistics run-card customers ws_1 --data-file card.json",],
+        },
+        "run-computation": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics run-computation <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const computation = requiredJsonInput(f, "--data, --data-file, or --stdin is required (computation settings).");
+                return c.statistics.runComputation(a[0], a[1], computation, f["project-key"]);
+            },
+            usage: "dss statistics run-computation <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Run a single computation in a worksheet context.",
+            examples: ["dss statistics run-computation customers ws_1 --data-file comp.json",],
+        },
+    },
+    discussion: {
+        list: {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss discussion list <objectType> <objectId> [--project-key KEY]");
+                return c.discussions.list(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss discussion list <objectType> <objectId> [--project-key KEY]",
+            description: "List discussions attached to a project object.",
+            examples: ["dss discussion list DATASET customers",],
+        },
+        get: {
+            handler: (c, a, f) => {
+                requireArgs(a, 3, "dss discussion get <objectType> <objectId> <discussionId> [--project-key KEY]");
+                return c.discussions.get(a[0], a[1], a[2], f["project-key"]);
+            },
+            usage: "dss discussion get <objectType> <objectId> <discussionId> [--project-key KEY]",
+            description: "Get one discussion with its replies.",
+            examples: ["dss discussion get DATASET customers d123",],
+        },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss discussion create <objectType> <objectId> --topic TEXT --reply TEXT [--project-key KEY]");
+                const topic = f["topic"];
+                const reply = f["reply"];
+                if (!topic || !reply) {
+                    throw new UsageError("--topic and --reply are required.", "missing_required_flag");
+                }
+                return c.discussions.create(a[0], a[1], topic, reply, f["project-key"]);
+            },
+            usage: "dss discussion create <objectType> <objectId> --topic TEXT --reply TEXT [--project-key KEY]",
+            description: "Create a discussion with its first reply.",
+            examples: ["dss discussion create DATASET customers --topic Schema --reply Please-review",],
+        },
+        reply: {
+            handler: (c, a, f) => {
+                requireArgs(a, 3, "dss discussion reply <objectType> <objectId> <discussionId> --text TEXT [--project-key KEY]");
+                const text = f["text"];
+                if (!text)
+                    throw new UsageError("--text is required.", "missing_required_flag");
+                return c.discussions.reply(a[0], a[1], a[2], text, f["project-key"]);
+            },
+            usage: "dss discussion reply <objectType> <objectId> <discussionId> --text TEXT [--project-key KEY]",
+            description: "Add a reply to an existing discussion.",
+            examples: ["dss discussion reply DATASET customers d123 --text Done",],
+        },
+    },
+    meaning: {
+        list: {
+            handler: (c) => c.meanings.list(),
+            usage: "dss meaning list",
+            description: "List user-defined meanings (column semantic types) on the instance.",
+            examples: ["dss meaning list",],
+        },
+        get: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss meaning get <meaningId>");
+                return c.meanings.get(a[0]);
+            },
+            usage: "dss meaning get <meaningId>",
+            description: "Get a user-defined meaning definition.",
+            examples: ["dss meaning get customer_type",],
+        },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 3, "dss meaning create <id> <label> <type> [--data JSON|--data-file PATH|--stdin]");
+                return c.meanings.create(a[0], a[1], a[2], jsonInput(f) ?? {});
+            },
+            usage: "dss meaning create <id> <label> <type> [--data JSON|--data-file PATH|--stdin]",
+            description: "Create a user-defined meaning (type e.g. VALUES_LIST, VALUES_MAPPING, PATTERN).",
+            examples: ["dss meaning create vip VIP VALUES_LIST",],
+        },
+        update: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss meaning update <meaningId> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (meaning definition).");
+                return c.meanings.update(a[0], body);
+            },
+            usage: "dss meaning update <meaningId> (--data JSON|--data-file PATH|--stdin)",
+            description: "Replace a user-defined meaning definition.",
+            examples: ["dss meaning update vip --data-file meaning.json",],
+        },
+    },
+    workspace: {
+        list: {
+            handler: (c) => c.workspaces.list(),
+            usage: "dss workspace list",
+            description: "List collaboration workspaces on the instance.",
+            examples: ["dss workspace list",],
+        },
+        get: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss workspace get <workspaceKey>");
+                return c.workspaces.get(a[0]);
+            },
+            usage: "dss workspace get <workspaceKey>",
+            description: "Get a workspace's settings.",
+            examples: ["dss workspace get MY_WS",],
+        },
+        create: {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (workspace definition).");
+                return c.workspaces.create(body);
+            },
+            usage: "dss workspace create (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a collaboration workspace.",
+            examples: ["dss workspace create --data-file ws.json",],
+        },
+        "update-settings": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss workspace update-settings <workspaceKey> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (workspace settings).");
+                await c.workspaces.updateSettings(a[0], body);
+                return { updated: a[0], };
+            },
+            usage: "dss workspace update-settings <workspaceKey> (--data JSON|--data-file PATH|--stdin)",
+            description: "Replace a workspace's settings (admin).",
+            examples: ["dss workspace update-settings MY_WS --data-file ws.json",],
+        },
+        delete: {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss workspace delete <workspaceKey>");
+                await c.workspaces.delete(a[0]);
+                return { deleted: a[0], };
+            },
+            usage: "dss workspace delete <workspaceKey>",
+            description: "Delete a workspace (admin).",
+            examples: ["dss workspace delete MY_WS",],
+        },
+        "list-objects": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss workspace list-objects <workspaceKey>");
+                return c.workspaces.listObjects(a[0]);
+            },
+            usage: "dss workspace list-objects <workspaceKey>",
+            description: "List objects shared in a workspace.",
+            examples: ["dss workspace list-objects MY_WS",],
+        },
+        "add-object": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss workspace add-object <workspaceKey> (--data JSON|--data-file PATH|--stdin)");
+                const object = requiredJsonInput(f, "--data, --data-file, or --stdin is required (object definition).");
+                return c.workspaces.addObject(a[0], object);
+            },
+            usage: "dss workspace add-object <workspaceKey> (--data JSON|--data-file PATH|--stdin)",
+            description: "Add an object (link or DSS object) to a workspace.",
+            examples: ["dss workspace add-object MY_WS --data-file object.json",],
+        },
+    },
+    metrics: {
+        "dataset-get": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss metrics dataset-get <dataset> [--project-key KEY]");
+                return c.metrics.getDatasetMetrics(a[0], f["project-key"]);
+            },
+            usage: "dss metrics dataset-get <dataset> [--project-key KEY]",
+            description: "Get the last computed metric values for a dataset.",
+            examples: ["dss metrics dataset-get customers",],
+        },
+        "dataset-compute": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss metrics dataset-compute <dataset> [--project-key KEY]");
+                return c.metrics.computeDatasetMetrics(a[0], f["project-key"]);
+            },
+            usage: "dss metrics dataset-compute <dataset> [--project-key KEY]",
+            description: "Compute the DSS-configured metrics for a dataset.",
+            examples: ["dss metrics dataset-compute customers",],
+        },
+        "dataset-history": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss metrics dataset-history <dataset> <metricId> [--project-key KEY]");
+                return c.metrics.getDatasetMetricHistory(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss metrics dataset-history <dataset> <metricId> [--project-key KEY]",
+            description: "Get the history of one dataset metric.",
+            examples: ["dss metrics dataset-history customers records:COUNT_RECORDS",],
+        },
+        "folder-get": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss metrics folder-get <folderId> [--project-key KEY]");
+                return c.metrics.getFolderMetrics(a[0], f["project-key"]);
+            },
+            usage: "dss metrics folder-get <folderId> [--project-key KEY]",
+            description: "Get the last computed metric values for a managed folder.",
+            examples: ["dss metrics folder-get aBcDeFgH",],
+        },
     },
     doctor: {
         run: {
@@ -2666,6 +3907,36 @@ const commands = {
             description: "List all datasets in a project.",
             examples: ["dss dataset list", "dss dataset list --project-key MYPROJ",],
         },
+        rename: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss dataset rename <oldName> <newName> [--project-key KEY]");
+                await c.datasets.rename(a[0], a[1], f["project-key"]);
+                return { renamed: a[0], to: a[1], };
+            },
+            usage: "dss dataset rename <oldName> <newName> [--project-key KEY]",
+            description: "Rename a dataset (updates downstream flow references).",
+            examples: ["dss dataset rename old_ds new_ds",],
+        },
+        "list-partitions": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss dataset list-partitions <name> [--project-key KEY]");
+                return c.datasets.listPartitions(a[0], f["project-key"]);
+            },
+            usage: "dss dataset list-partitions <name> [--project-key KEY]",
+            description: "List the partitions of a partitioned dataset.",
+            examples: ["dss dataset list-partitions events",],
+        },
+        clear: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss dataset clear <name> [--partitions SPEC] [--project-key KEY]");
+                const partitions = f["partitions"];
+                await c.datasets.clear(a[0], partitions, f["project-key"]);
+                return { cleared: a[0], partitions: partitions ?? "ALL", };
+            },
+            usage: "dss dataset clear <name> [--partitions SPEC] [--project-key KEY]",
+            description: "Clear a dataset's data (all, or a partition spec); keeps the dataset.",
+            examples: ["dss dataset clear staging", "dss dataset clear events --partitions 2024-01",],
+        },
         get: {
             handler: (c, a, f) => {
                 requireArgs(a, 1, "dss dataset get <name>");
@@ -2737,9 +4008,9 @@ const commands = {
                     timeoutMs: num(f["timeout"]),
                 });
             },
-            usage: "dss dataset preview <name> [--max-rows N] [--project-key KEY] [--timeout MS]",
-            description: "Preview dataset rows.",
-            examples: ["dss dataset preview orders", "dss dataset preview orders --max-rows 5",],
+            usage: "dss dataset preview <name> [--max-rows N|--rows N] [--project-key KEY] [--timeout MS]",
+            description: "Preview dataset rows (--rows is an alias for --max-rows).",
+            examples: ["dss dataset preview orders", "dss dataset preview orders --rows 5",],
         },
         metadata: {
             handler: (c, a, f) => {
@@ -2751,16 +4022,28 @@ const commands = {
             examples: ["dss dataset metadata orders",],
         },
         download: {
-            handler: (c, a, f) => {
+            handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss dataset download <name>");
-                return c.datasets.download(a[0], {
+                const result = await c.datasets.download(a[0], {
                     outputPath: f["output"],
                     projectKey: f["project-key"],
                     limit: num(f["limit"]),
                 });
+                if (result.truncated) {
+                    enqueueCliWarning({
+                        code: "dataset_download_truncated",
+                        message: `Download of '${a[0]}' stopped at the ${result.limit}-row cap; the dataset has more rows. `
+                            + "Re-run with --limit N for more, or read inside a recipe (get_dataframe) for the full data.",
+                        dataset: a[0],
+                        rows: result.rows,
+                        limit: result.limit,
+                        path: result.path,
+                    });
+                }
+                return result;
             },
             usage: "dss dataset download <name> [--output PATH] [--limit N] [--project-key KEY]",
-            description: "Download up to --limit rows (default 100k) as CSV; returns { path, rows, truncated, limit } so truncation is visible.",
+            description: "Download up to --limit rows (default 100k) as CSV; returns { path, rows, truncated, limit }. When truncated, a dataset_download_truncated warning is also written to stderr so the cap is never silent.",
             examples: ["dss dataset download orders", "dss dataset download orders --output ./data/",],
         },
         create: {
@@ -4452,6 +5735,7 @@ const commands = {
                     projectKey: f["project-key"],
                     timeoutMs: num(f["timeout"]),
                     keepScenario: f["keep"] === true,
+                    maxLogBytes: num(f["max-log-bytes"]),
                 });
                 const result = {
                     outcome: run.outcome,
@@ -4460,6 +5744,8 @@ const commands = {
                     elapsedMs: run.elapsedMs,
                     pollCount: run.pollCount,
                     output: run.output ?? "",
+                    logTruncated: run.logTruncated,
+                    maxLogBytes: run.maxLogBytes,
                 };
                 if (f["full-log"] === true || run.output === undefined) {
                     result.log = run.log;
@@ -4467,7 +5753,7 @@ const commands = {
                 return result;
             },
             usage: CODE_RUN_USAGE,
-            description: "Run one-off Python in a DSS code env via a throwaway custom-python scenario; returns the script's captured output (stdout+stderr) plus outcome/success. Pass --full-log for the raw DSS run log. Exits 4 on a non-SUCCESS outcome.",
+            description: "Run one-off Python in a DSS code env via a throwaway custom-python scenario; returns the script's captured output (stdout+stderr) plus outcome/success. Log retrieval is capped by --max-log-bytes (default 1048576); pass --full-log to include the capped raw DSS run log. Exits 4 on a non-SUCCESS outcome.",
             examples: [
                 "dss code run --file inspect.py",
                 "dss code run --file inspect.py --env py39_pandas",
@@ -4743,8 +6029,8 @@ function missingActionError(resource, validActions, usage) {
 function unknownResourceError(resource) {
     return new UsageError(`Unknown resource: ${resource}.`, "usage_error", COMMANDS_RUN_HINT, { resource, validResources: RESOURCE_NAMES, });
 }
-function unknownActionError(resource, action, validActions) {
-    return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", COMMANDS_RUN_HINT, { resource, action, validActions, });
+function unknownActionError(resource, action, validActions, hint) {
+    return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", hint ?? COMMANDS_RUN_HINT, { resource, action, validActions, });
 }
 function requireArgs(args, count, usage) {
     if (args.length < count) {
@@ -5364,7 +6650,7 @@ function inferSideEffect(resource, action) {
         return "write";
     if (READ_ACTIONS.has(action))
         return "read";
-    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove)/
+    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove|publish|activate|deploy|import|export|preload|upgrade|stop|restart|duplicate|put|rename|reply|compute)/
         .test(action)) {
         return "write";
     }
@@ -6774,8 +8060,9 @@ async function main() {
         }
         currentCommandContext.action = action;
         const authMeta = AUTH_ACTIONS[action];
-        if (!authMeta)
-            throw unknownActionError("auth", action, validActions);
+        if (!authMeta) {
+            throw unknownActionError("auth", action, validActions, "auth only supports 'login'. To check credentials/connectivity, run 'dss doctor'.");
+        }
         const result = await authMeta.handler(flags);
         writeCommandResult(result);
         return;