dataiku-sdk 3.3.0 → 3.5.0

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

@@ -1,26 +1,25 @@
 import { requiredStringFlag, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const analysisCommands = {
+export const analysisCommands = withUsage("analysis", {
     list: {
         handler: (c, _a, f) => c.analyses.list(f["project-key"]),
-        usage: "dss analysis list [--project-key KEY]",
         description: "List Visual ML analyses in a project.",
         examples: ["dss analysis list --project-key PROJECT",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss analysis get <analysisId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("analysis", "get"));
             return c.analyses.get(a[0], f["project-key"]);
         },
-        usage: "dss analysis get <analysisId> [--project-key KEY]",
         description: "Get a Visual ML analysis.",
         examples: ["dss analysis get ANALYSIS_ID --project-key PROJECT",],
     },
     create: {
         handler: async (c, _a, f) => {
-            const usage = "dss analysis create --input-dataset DS [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("analysis", "create");
             const inputDataset = requiredStringFlag(f, "input-dataset", usage);
             const projectKey = f["project-key"];
             const options = { inputDataset, projectKey, };
@@ -35,7 +34,6 @@ export const analysisCommands = {
             const created = await c.analyses.create(options);
             return { created: created.id, resource: "analysis", ...created, };
         },
-        usage: "dss analysis create --input-dataset DS [--dry-run] [--project-key KEY]",
         description: "Create a Visual ML analysis for an input dataset.",
         examples: [
             "dss analysis create --input-dataset customers --project-key PROJECT",
@@ -44,7 +42,7 @@ export const analysisCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss analysis delete <analysisId> [--if-exists] [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("analysis", "delete"));
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.analyses.get(a[0], projectKey));
@@ -57,11 +55,10 @@ export const analysisCommands = {
             await c.analyses.delete(a[0], projectKey);
             return { deleted: a[0], resource: "analysis", };
         },
-        usage: "dss analysis delete <analysisId> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a Visual ML analysis.",
         examples: [
             "dss analysis delete ANALYSIS_ID --if-exists --project-key PROJECT",
             "dss analysis delete ANALYSIS_ID --dry-run --project-key PROJECT",
         ],
     },
-};
+});

package/dist/src/cli/commands/api-deployer.js

@@ -1,9 +1,9 @@
 import { requiredJsonInput, } from "../coerce.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const apiDeployerCommands = {
+export const apiDeployerCommands = withUsage("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",],
     },
@@ -12,38 +12,33 @@ export const apiDeployerCommands = {
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "get-infra"));
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "delete-infra"));
             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",],
     },
@@ -52,52 +47,46 @@ export const apiDeployerCommands = {
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "get-service"));
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "delete-service"));
             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>");
+            requireArgs(a, 2, commandUsage("api-deployer", "publish-version"));
             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>");
+            requireArgs(a, 2, commandUsage("api-deployer", "delete-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",],
     },
@@ -106,65 +95,58 @@ export const apiDeployerCommands = {
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "get-deployment"));
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "deployment-status"));
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "deployment-settings"));
             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)");
+            requireArgs(a, 1, commandUsage("api-deployer", "save-deployment-settings"));
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "deploy"));
             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>");
+            requireArgs(a, 1, commandUsage("api-deployer", "delete-deployment"));
             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",],
     },
-};
+});

package/dist/src/cli/commands/api-service.js

@@ -1,45 +1,43 @@
-import { ClientValidationError, } from "../../errors.js";
+import { ClientValidationError, unexpectedResponseError, } from "../../errors.js";
 import { writeResponseToFile, } from "../../utils/response-file.js";
-import { stableHash, } from "../../utils/stable-hash.js";
+import { SHA256_HEX_PATTERN, stableHash, } from "../../utils/stable-hash.js";
 import { requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 function validateExpectHash(value) {
     if (value === undefined || value === false)
         return undefined;
-    if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value)) {
+    if (typeof value !== "string" || !SHA256_HEX_PATTERN.test(value)) {
         throw new ClientValidationError("Expected API service settings hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Run this update with --dry-run and capture currentHash before retrying.");
     }
     return value;
 }
-export const apiServiceCommands = {
+export const apiServiceCommands = withUsage("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]");
+            requireArgs(a, 1, commandUsage("api-service", "create"));
             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]");
+            requireArgs(a, 1, commandUsage("api-service", "get-settings"));
             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: async (c, a, f) => {
-            const usage = "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("api-service", "save-settings");
             requireArgs(a, 1, usage);
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (service settings).");
             const projectKey = f["project-key"];
@@ -71,13 +69,12 @@ export const apiServiceCommands = {
             const saved = await c.apiServices.saveSettings(a[0], body, projectKey, { expectHash, });
             return { saved: a[0], ...saved, };
         },
-        usage: "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]",
         description: "Replace an API service's settings wholesale (explicit replacement: the supplied object is PUT as-is, so fetch get-settings first). --expect-hash refuses the write when the stored settings changed since they were fetched; --dry-run reports current, next, and both hashes without writing.",
         examples: ["dss api-service save-settings my-service --data-file service.json --dry-run",],
     },
     "add-prediction-endpoint": {
         handler: async (c, a, f) => {
-            requireArgs(a, 3, "dss api-service add-prediction-endpoint <serviceId> <endpointId> <savedModelId> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 3, commandUsage("api-service", "add-prediction-endpoint"));
             const endpoint = {
                 id: a[1],
                 type: "STD_PREDICTION",
@@ -87,7 +84,6 @@ export const apiServiceCommands = {
                 return endpoint;
             return c.apiServices.addPredictionEndpoint(a[0], a[1], a[2], f["project-key"]);
         },
-        usage: "dss api-service add-prediction-endpoint <serviceId> <endpointId> <savedModelId> [--dry-run] [--project-key KEY]",
         description: "Add a saved-model prediction endpoint to an API service.",
         examples: [
             "dss api-service add-prediction-endpoint my-service predict churn-model",
@@ -96,29 +92,26 @@ export const apiServiceCommands = {
     },
     "list-packages": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss api-service list-packages <serviceId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("api-service", "list-packages"));
             const projectKey = f["project-key"];
             return c.apiServices.listPackages(a[0], projectKey);
         },
-        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]");
+            requireArgs(a, 2, commandUsage("api-service", "package-summary"));
             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> [--release-notes TEXT] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("api-service", "create-package"));
             return c.apiServices.createPackage(a[0], a[1], f["project-key"], typeof f["release-notes"] === "string" ? { releaseNotes: f["release-notes"], } : {});
         },
-        usage: "dss api-service create-package <serviceId> <packageId> [--release-notes TEXT] [--project-key KEY]",
         description: "Build a deployable package from the current service state; --release-notes forwards the documented releaseNotes query parameter.",
         examples: [
             "dss api-service create-package my-service v1",
@@ -127,43 +120,40 @@ export const apiServiceCommands = {
     },
     "delete-package": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss api-service delete-package <serviceId> <packageId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("api-service", "delete-package"));
             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]");
+            requireArgs(a, 2, commandUsage("api-service", "download-package"));
             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"]);
             if (!res.body) {
-                throw new Error("apiServices.downloadPackageArchive response did not include a body");
+                throw unexpectedResponseError("apiServices.downloadPackageArchive response did not include a body");
             }
             const bytes = await writeResponseToFile(out, res);
             return { path: out, bytes, };
         },
-        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> [--published-service-id ID] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("api-service", "publish-package"));
             return c.apiServices.publishPackage(a[0], a[1], f["project-key"], typeof f["published-service-id"] === "string"
                 ? { publishedServiceId: f["published-service-id"], }
                 : {});
         },
-        usage: "dss api-service publish-package <serviceId> <packageId> [--published-service-id ID] [--project-key KEY]",
         description: "Publish a package to the API Deployer; --published-service-id forwards the documented publishedServiceId query parameter (a new published service is created when no match exists; the service's own id is the server-side default).",
         examples: [
             "dss api-service publish-package my-service v1",
             "dss api-service publish-package my-service v1 --published-service-id=prod-churn",
         ],
     },
-};
+});

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

@@ -5,15 +5,16 @@ 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 +68,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 +95,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 +114,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",
@@ -388,7 +384,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 +404,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 +426,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 +435,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 +497,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 +505,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 +514,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 +522,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 +708,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 +716,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 +743,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 +750,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 +770,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 +824,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",
         ],
     },
-};
+});