dataiku-sdk 3.4.0 → 3.6.0

package/dist/src/cli/commands/app.js

@@ -1,19 +1,21 @@
 import { ClientValidationError, DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
-import { jsonInput, num, parseBooleanOption, plainRecord, requiredJsonInput, requiredStringFlag, stringField, } from "../coerce.js";
+import { asRecord, } from "../../utils/records.js";
+import { jsonInput, num, parseBooleanOption, requiredJsonInput, requiredStringFlag, stringField, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { appPermissionsHash, appPermissionsVerificationError, assertAppPermissionsSnapshotBinding, buildAppPermissionsSnapshot, diffAppPermissions, readAppPermissionsSnapshot, writeAppPermissionsSnapshot, } from "../helpers/app-permissions.js";
 import { createSuccessorInstance, futureTargetIdentity, generatedInstanceKey, isDefinitiveRejection, preflightSuccessorInstance, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
 import { CommandResultFailure, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
-const CREATE_INSTANCE_USAGE = "dss app create-instance <appId> (--data JSON|--data-file PATH|--stdin) [--wait] [--timeout MS] [--poll-interval MS]";
-const MANIFEST_VERSION_USAGE = "dss app manifest-version [--project-key KEY]";
-const SET_MANIFEST_VERSION_USAGE = "dss app set-manifest-version (--manifest-version V|--version-notes NOTES) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
-const CREATE_SUCCESSOR_USAGE = "dss app create-successor-instance <appId> --from KEY [--to KEY] [--name NAME] [--copy-permissions] [--timeout MS] [--poll-interval MS] [--dry-run] [--record-cleanup PATH]";
-const SUCCESSOR_PREFLIGHT_USAGE = "dss app successor-preflight <appId> --from KEY [--to KEY] [--name NAME] [--copy-permissions]";
-const VERIFY_INSTANCE_USAGE = "dss app verify-instance <appId> --project-key KEY [--expect-version V]";
-const DELETE_INSTANCE_USAGE = "dss app delete-instance --project-key KEY [--future-id ID] [--expect-project-incarnation SHA256] [--unconfirmed-creation] [--timeout MS] [--poll-interval MS]";
-const CREATE_INSTANCE_INDETERMINATE_REMEDIATION = "DSS may have accepted the creation, but no future ID or project incarnation authorizes cleanup. Inspect `dss app instances <appId>` and DSS task history; delete only after creation is known terminal and the target identity is verified.";
+const CREATE_INSTANCE_USAGE = commandUsage("app", "create-instance");
+const MANIFEST_VERSION_USAGE = commandUsage("app", "manifest-version");
+const SET_MANIFEST_VERSION_USAGE = commandUsage("app", "set-manifest-version");
+const CREATE_SUCCESSOR_USAGE = commandUsage("app", "create-successor-instance");
+const SUCCESSOR_PREFLIGHT_USAGE = commandUsage("app", "successor-preflight");
+const VERIFY_INSTANCE_USAGE = commandUsage("app", "verify-instance");
+const DELETE_INSTANCE_USAGE = commandUsage("app", "delete-instance");
+const CREATE_INSTANCE_INDETERMINATE_REMEDIATION = `DSS may have accepted the creation, but no future ID or project incarnation authorizes cleanup. Inspect \`${commandUsage("app", "instances")}\` and DSS task history; delete only after creation is known terminal and the target identity is verified.`;
 const CREATE_INSTANCE_REJECTED_REMEDIATION = "DSS refused the creation request, so no instance project was created: fix the reported problem and retry. If the target key itself is the problem, rerun create-instance with targetProjectKey omitted to generate a fresh random key (the generated key is a new key, never the rejected one).";
 const DELETE_INSTANCE_FUTURE_REMEDIATION = "The supplied creation future could not authorize deletion. Inspect that future and the target project, then retry only with a future whose terminal result reports this project.";
 const DELETE_INSTANCE_UNCONFIRMED_REMEDIATION = "Creation may still be running and DSS returned no future ID. Inspect the app's instances and wait until creation is known terminal before running delete-instance without --unconfirmed-creation.";
@@ -67,28 +69,25 @@ function optionalSuccessorTarget(flags, usage) {
     }
     return value.trim();
 }
-export const appCommands = {
+export const appCommands = withUsage("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>");
+            requireArgs(a, 1, commandUsage("app", "manifest"));
             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>");
+            requireArgs(a, 1, commandUsage("app", "instances"));
             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",],
     },
@@ -97,7 +96,6 @@ export const appCommands = {
             requireNoArgs(a, MANIFEST_VERSION_USAGE);
             return c.applications.getManifestVersion(f["project-key"]);
         },
-        usage: MANIFEST_VERSION_USAGE,
         description: "Read the app-manifest version of a Dataiku App template or app-instance project: the raw persisted string only, never a synthesized default.",
         examples: ["dss app manifest-version --project-key MYAPP_TEMPLATE",],
     },
@@ -117,7 +115,6 @@ export const appCommands = {
                 requiredExternalGates: [VISUAL_UI_GATE,],
             };
         },
-        usage: VERIFY_INSTANCE_USAGE,
         description: "Read-only API readiness check for an app instance: project type, registration under the app, authoritative raw manifest version, and manifest reference validation. The visual UI remains an explicit external SSO gate.",
         examples: [
             "dss app verify-instance my-app --project-key RELEASE_INSTANCE",
@@ -184,7 +181,7 @@ export const appCommands = {
                     ...safeErrorSummary(error),
                 };
             }
-            const instance = plainRecord(created);
+            const instance = asRecord(created);
             if (!instance) {
                 return {
                     success: false,
@@ -388,7 +385,6 @@ export const appCommands = {
                     : {}),
             };
         },
-        usage: CREATE_INSTANCE_USAGE,
         description: "Create an app instance from a Dataiku App template, optionally waiting for the creation future. Omit targetProjectKey to generate a random APP_ key (the default display name); explicit keys are trimmed and must be absent.",
         examples: [
             'dss app create-instance my-app --data \'{"targetProjectKey":"NEWPROJ"}\'',
@@ -409,7 +405,6 @@ export const appCommands = {
                 dryRun: true,
             }, SUCCESSOR_PREFLIGHT_USAGE);
         },
-        usage: SUCCESSOR_PREFLIGHT_USAGE,
         description: "Run every read-only successor gate before changing the template version: validate the template, verify the predecessor, prove an explicit --to target absent, and optionally snapshot the predecessor ACL. Omit --to to preflight generated-key mode, where no target exists yet and nothing is probed or allocated.",
         examples: [
             "dss app successor-preflight my-app --from OLD_INSTANCE --to NEW_INSTANCE",
@@ -432,7 +427,6 @@ export const appCommands = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
             }, CREATE_SUCCESSOR_USAGE);
         },
-        usage: CREATE_SUCCESSOR_USAGE,
         description: "Create a new app instance from the current template version alongside an existing instance. An explicit --to keeps the strict caller-chosen-key contract (proven absent before the single POST); omit --to to generate the successor key once during apply and let the terminal future name it. The predecessor is never modified and is retired separately and deliberately; the creation future is always awaited.",
         examples: [
             "dss app create-successor-instance my-app --from OLD_INSTANCE --to NEW_INSTANCE",
@@ -442,20 +436,18 @@ export const appCommands = {
     },
     "instance-manifest": {
         handler: (c, a, f) => {
-            requireNoArgs(a, "dss app instance-manifest [--project-key KEY]");
+            requireNoArgs(a, commandUsage("app", "instance-manifest"));
             return c.applications.getInstanceManifest(f["project-key"]);
         },
-        usage: "dss app instance-manifest [--project-key KEY]",
         description: "Get the app manifest of a Dataiku App template or app-instance project.",
         examples: ["dss app instance-manifest --project-key MYINSTANCE",],
     },
     "save-instance-manifest": {
         handler: (c, a, f) => {
-            requireNoArgs(a, "dss app save-instance-manifest (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+            requireNoArgs(a, commandUsage("app", "save-instance-manifest"));
             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 a Dataiku App template project (homepage sections, use-as-recipe settings). Classic app-instance project manifests are read-only through this endpoint.",
         examples: [
             "dss app save-instance-manifest --data-file manifest.json --project-key MYAPP_TEMPLATE",
@@ -506,7 +498,6 @@ export const appCommands = {
                 uiPublicationVerified: false,
             };
         },
-        usage: SET_MANIFEST_VERSION_USAGE,
         description: "Set the raw app-manifest version and/or version notes of a Dataiku App template through the public app-manifest endpoint. This is not a publish transaction: the persisted string becomes the template version that new instances inherit, and the visual UI remains an external gate.",
         examples: [
             "dss app set-manifest-version --manifest-version 2.0.0 --project-key MYAPP_TEMPLATE",
@@ -515,7 +506,7 @@ export const appCommands = {
     },
     "validate-manifest": {
         handler: async (c, a, f) => {
-            requireNoArgs(a, "dss app validate-manifest [--data JSON|--data-file PATH|--stdin] [--project-key KEY]");
+            requireNoArgs(a, commandUsage("app", "validate-manifest"));
             const payload = jsonInput(f);
             const manifest = payload ?? await c.applications.getInstanceManifest(f["project-key"]);
             const result = await c.applications.validateAppManifest(manifest, f["project-key"]);
@@ -524,7 +515,6 @@ export const appCommands = {
             }
             return result;
         },
-        usage: "dss app validate-manifest [--data JSON|--data-file PATH|--stdin] [--project-key KEY]",
         description: "Validate an app manifest against source-verifiable reference data (scenario IDs, managed-folder IDs, variable names). Without a payload, reads the target project's app manifest.",
         examples: [
             "dss app validate-manifest --data-file manifest.json --project-key MYAPP_TEMPLATE",
@@ -533,11 +523,10 @@ export const appCommands = {
     },
     "compare-manifest": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss app compare-manifest <appId> --project-key KEY");
-            const projectKey = requiredStringFlag(f, "project-key", "dss app compare-manifest <appId> --project-key KEY");
+            requireArgs(a, 1, commandUsage("app", "compare-manifest"));
+            const projectKey = requiredStringFlag(f, "project-key", commandUsage("app", "compare-manifest"));
             return c.applications.compareAppManifest(a[0], projectKey);
         },
-        usage: "dss app compare-manifest <appId> --project-key KEY",
         description: "Compare a Dataiku App template with the target app instance (normalized hashes and deterministic path-level differences; only project identity fields are omitted).",
         examples: ["dss app compare-manifest my-app --project-key MYINSTANCE",],
     },
@@ -720,7 +709,6 @@ export const appCommands = {
                 pollCount: waited.pollCount,
             };
         },
-        usage: DELETE_INSTANCE_USAGE,
         description: "Delete an app-instance project (destructive: removes the instance project). With --future-id, requires the recorded project-incarnation hash, waits without aborting, verifies that the terminal future reports this target, rechecks the incarnation, then deletes.",
         examples: [
             "dss app delete-instance --project-key MYINSTANCE",
@@ -729,16 +717,15 @@ export const appCommands = {
     },
     "business-app-instance-permissions": {
         handler: (c, a) => {
-            requireArgs(a, 3, "dss app business-app-instance-permissions <businessAppId> <instanceProjectKey> <userLogin>");
+            requireArgs(a, 3, commandUsage("app", "business-app-instance-permissions"));
             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",],
     },
     "permissions-snapshot": {
         handler: async (c, _a, f) => {
-            const usage = "dss app permissions-snapshot --output PATH [--project-key KEY]";
+            const usage = commandUsage("app", "permissions-snapshot");
             requireNoArgs(_a, usage);
             const output = requiredStringFlag(f, "output", usage);
             const projectKey = c.resolveProjectKey(f["project-key"]);
@@ -757,7 +744,6 @@ export const appCommands = {
                 capturedAt: snapshot.capturedAt,
             };
         },
-        usage: "dss app permissions-snapshot --output PATH [--project-key KEY]",
         description: "Snapshot a project's access-control permissions to a local owner-only JSON file with a canonical integrity hash; commit it only when repository policy permits.",
         examples: [
             "dss app permissions-snapshot --output app-permissions.json --project-key MYINSTANCE",
@@ -765,7 +751,7 @@ export const appCommands = {
     },
     "permissions-diff": {
         handler: async (c, _a, f) => {
-            const usage = "dss app permissions-diff --file PATH [--project-key KEY]";
+            const usage = commandUsage("app", "permissions-diff");
             requireNoArgs(_a, usage);
             const file = requiredStringFlag(f, "file", usage);
             const snapshot = readAppPermissionsSnapshot(file);
@@ -785,13 +771,12 @@ export const appCommands = {
                 differences: diff.differences,
             };
         },
-        usage: "dss app permissions-diff --file PATH [--project-key KEY]",
         description: "Compare a permission snapshot file against the live project permissions, returning deterministic path-level differences.",
         examples: ["dss app permissions-diff --file app-permissions.json --project-key MYINSTANCE",],
     },
     "permissions-restore": {
         handler: async (c, _a, f) => {
-            const usage = "dss app permissions-restore --file PATH [--project-key KEY] [--dry-run]";
+            const usage = commandUsage("app", "permissions-restore");
             requireNoArgs(_a, usage);
             const file = requiredStringFlag(f, "file", usage);
             const snapshot = readAppPermissionsSnapshot(file);
@@ -840,10 +825,9 @@ export const appCommands = {
                 applied: true,
             };
         },
-        usage: "dss app permissions-restore --file PATH [--project-key KEY] [--dry-run]",
         description: "Restore a project's permissions from a snapshot file: hash-verifies the file, refuses cross-project restores, reads before writing, only PUTs when changed, and refetches to verify the result.",
         examples: [
             "dss app permissions-restore --file app-permissions.json --project-key MYINSTANCE --dry-run",
         ],
     },
-};
+});

package/dist/src/cli/commands/bundle.js

@@ -1,16 +1,17 @@
+import { unexpectedResponseError, } from "../../errors.js";
 import { writeResponseToFile, } from "../../utils/response-file.js";
 import { json, parseBooleanOption, } from "../coerce.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
-export const bundleCommands = {
+export const bundleCommands = withUsage("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) => {
-            const usage = "dss bundle export <bundleId> [--release-notes TEXT] [--evaluate-standards-checks true|false] [--project-key KEY]";
+            const usage = commandUsage("bundle", "export");
             requireArgs(a, 1, usage);
             await c.bundles.exportBundle(a[0], f["project-key"], {
                 ...(typeof f["release-notes"] === "string" ? { releaseNotes: f["release-notes"], } : {}),
@@ -22,7 +23,6 @@ export const bundleCommands = {
             });
             return { exported: a[0], };
         },
-        usage: "dss bundle export <bundleId> [--release-notes TEXT] [--evaluate-standards-checks true|false] [--project-key KEY]",
         description: "Create an exported Design-node bundle. --release-notes forwards the documented releaseNotes parameter; --evaluate-standards-checks toggles the documented Project Standards Checks evaluation (default true; this instance forbids disabling it). DSS refuses re-exporting an existing bundle id — delete-exported first to replace one.",
         examples: [
             "dss bundle export v1",
@@ -31,40 +31,37 @@ export const bundleCommands = {
     },
     "delete-exported": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss bundle delete-exported <bundleId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("bundle", "delete-exported"));
             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]");
+            requireArgs(a, 1, commandUsage("bundle", "download-exported"));
             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"]);
             if (!res.body) {
-                throw new Error("bundles.downloadExportedArchive response did not include a body");
+                throw unexpectedResponseError("bundles.downloadExportedArchive response did not include a body");
             }
             const bytes = await writeResponseToFile(out, res);
             return { path: out, bytes, };
         },
-        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) => {
-            const usage = "dss bundle publish <bundleId> [--published-project-key KEY] [--project-key KEY]";
+            const usage = commandUsage("bundle", "publish");
             requireArgs(a, 1, usage);
             return c.bundles.publish(a[0], f["project-key"], typeof f["published-project-key"] === "string"
                 ? { publishedProjectKey: f["published-project-key"], }
                 : {});
         },
-        usage: "dss bundle publish <bundleId> [--published-project-key KEY] [--project-key KEY]",
         description: "Publish a Design-node bundle to the Project Deployer; --published-project-key forwards the documented publishedProjectKey query parameter (a new published project is created when no match exists; the source project's key is the server-side default).",
         examples: [
             "dss bundle publish v1",
@@ -73,32 +70,29 @@ export const bundleCommands = {
     },
     "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]");
+            requireArgs(a, 1, commandUsage("bundle", "import-from-archive"));
             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]");
+            requireArgs(a, 1, commandUsage("bundle", "import-from-stream"));
             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) => {
-            const usage = "dss bundle activate <bundleId> [--scenarios JSON] [--project-key KEY]";
+            const usage = commandUsage("bundle", "activate");
             requireArgs(a, 1, usage);
             const rawScenarios = f["scenarios"];
             let scenariosToEnable;
@@ -108,13 +102,12 @@ export const bundleCommands = {
                     || parsed === null
                     || Array.isArray(parsed)
                     || !Object.values(parsed).every((value) => typeof value === "boolean")) {
-                    throw new UsageError("--scenarios must be a JSON object mapping scenario IDs to true|false. Usage: dss bundle activate <bundleId> --scenarios '{\"daily_build\":true}'");
+                    throw new UsageError(`--scenarios must be a JSON object mapping scenario IDs to true|false. Usage: ${commandUsage("bundle", "activate")}`);
                 }
                 scenariosToEnable = parsed;
             }
             return c.bundles.activate(a[0], f["project-key"], scenariosToEnable !== undefined ? { scenariosToEnable, } : {});
         },
-        usage: "dss bundle activate <bundleId> [--scenarios JSON] [--project-key KEY]",
         description: "Activate an imported Automation-node bundle; --scenarios forwards the documented scenario-ID-to-enabled dict as the scenariosActiveOnActivation body.",
         examples: [
             "dss bundle activate v1",
@@ -123,21 +116,19 @@ export const bundleCommands = {
     },
     preload: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss bundle preload <bundleId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("bundle", "preload"));
             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]");
+            requireArgs(a, 1, commandUsage("bundle", "delete-imported"));
             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",],
     },
-};
+});

package/dist/src/cli/commands/business-app.js

@@ -1,76 +1,69 @@
 import { requiredJsonInput, } from "../coerce.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const businessAppCommands = {
+export const businessAppCommands = withUsage("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>");
+            requireArgs(a, 1, commandUsage("business-app", "get"));
             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>");
+            requireArgs(a, 1, commandUsage("business-app", "settings"));
             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)");
+            requireArgs(a, 1, commandUsage("business-app", "save-settings"));
             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>");
+            requireArgs(a, 1, commandUsage("business-app", "instances"));
             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)");
+            requireArgs(a, 1, commandUsage("business-app", "create-instance"));
             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>");
+            requireArgs(a, 2, commandUsage("business-app", "upgrade-instance"));
             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>");
+            requireArgs(a, 1, commandUsage("business-app", "install-from-archive"));
             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",],
     },
-};
+});