dataiku-sdk 3.4.0 → 3.6.0

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

@@ -5,8 +5,9 @@ import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { jsonInput, num, requiredJsonInput, requiredStringFlag, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { CommandResultFailure, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
-const INSPECT_ARCHIVE_USAGE = "dss project inspect-archive <file>";
+const INSPECT_ARCHIVE_USAGE = commandUsage("project", "inspect-archive");
 function flowRenderFormat(value) {
     if (value === undefined)
         return undefined;
@@ -19,28 +20,24 @@ function inspectArchiveCommand(args) {
     requireArgs(args, 1, INSPECT_ARCHIVE_USAGE);
     return inspectProjectArchive(args[0]);
 }
-export const projectCommands = {
+export const projectCommands = withUsage("project", {
     list: {
         handler: (c) => c.projects.list(),
-        usage: "dss project list",
         description: "List all accessible projects.",
         examples: ["dss project list",],
     },
     get: {
         handler: (c, _a, f) => c.projects.get(f["project-key"]),
-        usage: "dss project get [--project-key KEY]",
         description: "Get project settings and metadata.",
         examples: ["dss project get", "dss project get --project-key MYPROJ",],
     },
     metadata: {
         handler: (c, _a, f) => c.projects.metadata(f["project-key"]),
-        usage: "dss project metadata [--project-key KEY]",
         description: "Get project-level metadata (tags, labels, custom fields).",
         examples: ["dss project metadata", "dss project metadata --project-key MYPROJ",],
     },
     flow: {
         handler: (c, _a, f) => c.projects.flow(f["project-key"]),
-        usage: "dss project flow [--project-key KEY]",
         description: "Get the raw flow graph (all datasets, recipes, and edges).",
         examples: ["dss project flow", "dss project flow --project-key MYPROJ",],
     },
@@ -57,7 +54,6 @@ export const projectCommands = {
             num(f["max-nodes"], "--max-nodes");
             num(f["max-edges"], "--max-edges");
         },
-        usage: "dss project map [--max-nodes N] [--max-edges N] [--include-raw] [--render ascii|mermaid] [--project-key KEY]",
         description: "Get an analyzed flow map with zones, layers, components, and diagnostics.",
         examples: [
             "dss project map",
@@ -68,20 +64,19 @@ export const projectCommands = {
     },
     create: {
         handler: (c, a, f) => {
-            const usage = "dss project create <projectKey> <name> --owner LOGIN [--data JSON|--data-file PATH|--stdin]";
+            const usage = commandUsage("project", "create");
             requireArgs(a, 2, usage);
             const owner = f["owner"];
             if (!owner)
                 throw new UsageError(`--owner is required. Usage: ${usage}`);
             return c.projects.createProject(a[0], a[1], owner, jsonInput(f));
         },
-        usage: "dss project create <projectKey> <name> --owner LOGIN [--data JSON|--data-file PATH|--stdin]",
         description: "Create a new project with owner login and optional settings.",
         examples: ["dss project create MY_PROJ MyProject --owner alice",],
     },
     delete: {
         handler: async (c, a, f) => {
-            const usage = "dss project delete <projectKey> [--drop-data] [--if-exists] [--dry-run] [--expect-project-incarnation HASH]";
+            const usage = commandUsage("project", "delete");
             requireArgs(a, 1, usage);
             const projectKey = a[0];
             const expectedIncarnation = f["expect-project-incarnation"] === undefined
@@ -148,35 +143,32 @@ export const projectCommands = {
                     : {}),
             };
         },
-        usage: "dss project delete <projectKey> [--drop-data] [--if-exists] [--dry-run] [--expect-project-incarnation HASH]",
         description: "Delete a project (destructive). --drop-data also clears managed datasets; --if-exists treats an absent project as already deleted; --dry-run verifies without deleting; --expect-project-incarnation HASH refuses deletion unless the project still matches the recorded incarnation.",
         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]");
+            requireArgs(a, 3, commandUsage("project", "duplicate"));
             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]");
+            requireArgs(a, 1, commandUsage("project", "export"));
             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, f) => {
-            const usage = "dss project import <filePath> [--target-project-key KEY] [--data JSON|--data-file PATH|--stdin]";
+            const usage = commandUsage("project", "import");
             requireArgs(a, 1, usage);
             const settings = jsonInput(f) ?? {};
             const rawTarget = f["target-project-key"];
@@ -200,7 +192,6 @@ export const projectCommands = {
             }
             return result;
         },
-        usage: "dss project import <filePath> [--target-project-key KEY] [--data JSON|--data-file PATH|--stdin]",
         description: "Upload and process a project archive, optionally overriding its project key. The archive is validated locally before upload; verified success reports the used project key, explicit request/actual remapping, and the landed incarnation hash.",
         examples: [
             "dss project import ./my_proj.zip",
@@ -210,7 +201,6 @@ export const projectCommands = {
     "inspect-archive": {
         handler: async (_c, a) => inspectArchiveCommand(a),
         localHandler: inspectArchiveCommand,
-        usage: INSPECT_ARCHIVE_USAGE,
         description: "Read-only local inspection of a project export archive: member names, sizes, manifest validity, archive issues, and the source project key. Never contacts DSS.",
         examples: ["dss project inspect-archive ./my_proj.zip",],
     },
@@ -220,13 +210,11 @@ export const projectCommands = {
             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",],
     },
     "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",],
     },
@@ -244,7 +232,6 @@ export const projectCommands = {
             await c.projects.setMetadata(f["project-key"], metadata);
             return { updated: true, };
         },
-        usage: "dss project metadata-set (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Replace project metadata with a full object obtained from a previous metadata GET. Fields absent from the payload are removed.",
         examples: [
             "dss project metadata-set --data-file metadata.json --project-key MY_PROJ --dry-run",
@@ -252,7 +239,6 @@ export const projectCommands = {
     },
     "tags-get": {
         handler: (c, _a, f) => c.projects.tags(f["project-key"]),
-        usage: "dss project tags-get [--project-key KEY]",
         description: "Get project-level tags as a dictionary of tag name to display settings.",
         examples: ["dss project tags-get", "dss project tags-get --project-key MY_PROJ",],
     },
@@ -270,7 +256,6 @@ export const projectCommands = {
             await c.projects.setTags(f["project-key"], tags);
             return { updated: true, };
         },
-        usage: "dss project tags-set (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Replace project tags with a full object obtained from a previous tags GET. Tags absent from the payload are removed.",
         examples: [
             'dss project tags-set --data \'{"tags":{"production":{"color":"#28aadd"}}}\' --project-key MY_PROJ --dry-run',
@@ -278,7 +263,6 @@ export const projectCommands = {
     },
     "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",],
     },
@@ -291,8 +275,7 @@ export const projectCommands = {
             await c.projects.setSettings(projectKey, next);
             return { updated: true, };
         },
-        usage: "dss project settings-set (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
         description: "Update a project's settings via JSON merge.",
         examples: ["dss project settings-set --data-file settings.json --project-key MY_PROJ",],
     },
-};
+});

package/dist/src/cli/commands/recipe.d.ts

@@ -1,2 +1,18 @@
 import type { CommandMeta } from "../types.js";
+/** Maps `recipe create` flags to SDK options; shared by the handler and `--plan`. */
+export declare function recipeCreateOptionsFromFlags(f: Record<string, string | boolean>): {
+    type: string;
+    name: string | undefined;
+    inputDatasets: string[] | undefined;
+    outputDataset: string | undefined;
+    outputFolder: string | undefined;
+    outputConnection: string | undefined;
+    joinOn?: string[] | undefined;
+    joinType?: string | undefined;
+    fuzzyOn?: string[] | undefined;
+    fuzzyDistance?: string | undefined;
+    fuzzyThreshold?: number | undefined;
+    fuzzyNormalize: boolean;
+    projectKey: string | undefined;
+};
 export declare const recipeCommands: Record<string, CommandMeta>;

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

@@ -1,12 +1,14 @@
 import { readFileSync, } from "node:fs";
 import { writeFile, } from "node:fs/promises";
 import { join, } from "node:path";
+import { ClientValidationError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jobLogFilterFromFlag, jsonInput, maxLogLinesFromFlags, normalizeLineEndings, num, recipeInputDatasetsFromFlags, requiredJsonInput, requiredStringFlag, rewritePairsFromFlags, sha256Hex, splitCsvFlag, stableHash, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
 import { ensureRecipeBackupDir, readRecipeBackup, recipeBackupDocument, recipeBackupPath, recipeCodeEnv, recipeGraph, recipeInputItemRef, recipeRoleInputItems, recipeRunShouldWait, writeRecipeBackup, } from "../helpers/recipe.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 /** Read a local recipe file before any DSS request, mapping read failures to usage validation. */
 function readRecipeFile(filePath, flagName) {
@@ -59,27 +61,80 @@ function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
     }
     return lines.join("\n");
 }
-export const recipeCommands = {
+/** Maps `recipe create` flags to SDK options; shared by the handler and `--plan`. */
+export function recipeCreateOptionsFromFlags(f) {
+    const type = f["type"];
+    if (!type) {
+        throw new UsageError(`--type is required. Usage: ${commandUsage("recipe", "create")}`);
+    }
+    const outputDataset = f["output"];
+    const outputFolder = f["output-folder"];
+    if (outputDataset && outputFolder) {
+        throw new UsageError("--output and --output-folder are mutually exclusive.");
+    }
+    if (!outputDataset && !outputFolder) {
+        throw new UsageError(`--output or --output-folder is required. Usage: ${commandUsage("recipe", "create")}`);
+    }
+    if (outputFolder && !f["output-connection"]) {
+        throw new UsageError("--output-connection is required when using --output-folder.");
+    }
+    const name = f["name"];
+    const pk = f["project-key"];
+    const inputDatasets = recipeInputDatasetsFromFlags(f);
+    const joinColumns = splitCsvFlag(f["join-on"]);
+    const fuzzyColumns = splitCsvFlag(f["fuzzy-on"]);
+    const rawFuzzyDistance = f["fuzzy-distance"];
+    let fuzzyDistance;
+    if (typeof rawFuzzyDistance === "string") {
+        const normalized = rawFuzzyDistance.trim().toUpperCase();
+        if (![
+            "DAMERAU_LEVENSHTEIN",
+            "HAMMING",
+            "JACCARD",
+            "COSINE",
+            "EUCLIDEAN",
+        ].includes(normalized)) {
+            throw new UsageError("--fuzzy-distance must be one of DAMERAU_LEVENSHTEIN, HAMMING, JACCARD, COSINE, or EUCLIDEAN.", "invalid_enum");
+        }
+        fuzzyDistance = normalized;
+    }
+    const fuzzyThreshold = num(f["fuzzy-threshold"], "--fuzzy-threshold");
+    const payload = {
+        type,
+        name,
+        inputDatasets,
+        outputDataset,
+        outputFolder,
+        outputConnection: f["output-connection"],
+        ...(joinColumns.length > 0 ? { joinOn: joinColumns, } : {}),
+        ...(typeof f["join-type"] === "string" ? { joinType: f["join-type"], } : {}),
+        ...(fuzzyColumns.length > 0 ? { fuzzyOn: fuzzyColumns, } : {}),
+        ...(fuzzyDistance ? { fuzzyDistance, } : {}),
+        ...(fuzzyThreshold !== undefined ? { fuzzyThreshold, } : {}),
+        fuzzyNormalize: f["normalize"] === true,
+        projectKey: pk,
+    };
+    return payload;
+}
+export const recipeCommands = withUsage("recipe", {
     list: {
         handler: (c, _a, f) => c.recipes.list(f["project-key"]),
-        usage: "dss recipe list [--project-key KEY]",
         description: "List all recipes in a project.",
         examples: ["dss recipe list",],
     },
     metadata: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss recipe metadata <name>");
+            requireArgs(a, 1, commandUsage("recipe", "metadata"));
             return c.recipes.metadata(a[0], {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss recipe metadata <name> [--project-key KEY]",
         description: "Get recipe metadata (label, description, tags, custom fields).",
         examples: ["dss recipe metadata compute_orders",],
     },
     "metadata-set": {
         handler: async (c, a, f) => {
-            const usage = "dss recipe metadata-set <name> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("recipe", "metadata-set");
             requireArgs(a, 1, usage);
             const metadata = requiredJsonInput(f, "--data, --data-file, or --stdin is required (full metadata object).");
             const pk = f["project-key"];
@@ -95,7 +150,6 @@ export const recipeCommands = {
             await c.recipes.setMetadata(a[0], metadata, { projectKey: pk, });
             return { updated: a[0], resource: "recipe", };
         },
-        usage: "dss recipe metadata-set <name> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Replace recipe metadata with a full object obtained from a previous metadata GET. Fields absent from the payload are removed.",
         examples: [
             'dss recipe metadata-set compute_orders --data \'{"label":"Orders"}\' --dry-run',
@@ -103,13 +157,12 @@ export const recipeCommands = {
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss recipe get <name>");
+            requireArgs(a, 1, commandUsage("recipe", "get"));
             return c.recipes.get(a[0], {
                 includePayload: f["include-payload"] === true && f["no-payload"] !== true,
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss recipe get <name> [--include-payload|--no-payload] [--project-key KEY]",
         description: "Get compact recipe settings unless --include-payload is set.",
         examples: [
             "dss recipe get compute_orders",
@@ -119,18 +172,17 @@ export const recipeCommands = {
     },
     "validate-graph": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss recipe validate-graph <name>");
+            requireArgs(a, 1, commandUsage("recipe", "validate-graph"));
             return c.recipes.validateGraph(a[0], {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss recipe validate-graph <name> [--project-key KEY]",
         description: "Validate declared recipe input/output graph references before building.",
         examples: ["dss recipe validate-graph compute_orders",],
     },
     run: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss recipe run <name>");
+            requireArgs(a, 1, commandUsage("recipe", "run"));
             const pk = f["project-key"];
             const wait = recipeRunShouldWait(f);
             const options = {
@@ -163,7 +215,6 @@ export const recipeCommands = {
             }
             return c.recipes.run(a[0], options);
         },
-        usage: "dss recipe run <name> [--wait|--no-wait] [--build-mode MODE] [--include-logs] [--log-filter stdout|stderr|user|errors] [--summary] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--partition PARTITION] [--dry-run] [--project-key KEY]",
         description: "Run a recipe by resolving its outputs and submitting the correct dataset or managed-folder build job. --timeout defaults to 120000 ms and --poll-interval to 2000 ms.",
         examples: [
             "dss recipe run compute_orders --wait",
@@ -173,7 +224,7 @@ export const recipeCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss recipe delete <name>");
+            requireArgs(a, 1, commandUsage("recipe", "delete"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.recipes.get(a[0], { projectKey: pk, includePayload: true, }));
@@ -186,19 +237,17 @@ export const recipeCommands = {
             await c.recipes.delete(a[0], pk);
             return { deleted: a[0], resource: "recipe", };
         },
-        usage: "dss recipe delete <name> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a recipe.",
         examples: ["dss recipe delete compute_orders", "dss recipe delete compute_orders --if-exists",],
     },
     download: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss recipe download <name>");
+            requireArgs(a, 1, commandUsage("recipe", "download"));
             return c.recipes.download(a[0], {
                 outputPath: f["output"],
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss recipe download <name> [--output PATH] [--project-key KEY]",
         description: "Download recipe definition as JSON.",
         examples: [
             "dss recipe download compute_orders",
@@ -207,13 +256,12 @@ export const recipeCommands = {
     },
     "download-code": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss recipe download-code <name>");
+            requireArgs(a, 1, commandUsage("recipe", "download-code"));
             return c.recipes.downloadCode(a[0], {
                 outputPath: f["output"],
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss recipe download-code <name> [--output PATH] [--project-key KEY]",
         description: "Download the code payload of a recipe.",
         examples: [
             "dss recipe download-code compute_orders",
@@ -222,57 +270,9 @@ export const recipeCommands = {
     },
     create: {
         handler: async (c, _a, f) => {
-            const type = f["type"];
-            if (!type) {
-                throw new UsageError("--type is required. Usage: dss recipe create --type TYPE [--input DS] (--output DS | --output-folder FOLDER_ID)");
-            }
-            const outputDataset = f["output"];
-            const outputFolder = f["output-folder"];
-            if (outputDataset && outputFolder) {
-                throw new UsageError("--output and --output-folder are mutually exclusive.");
-            }
-            if (!outputDataset && !outputFolder) {
-                throw new UsageError("--output or --output-folder is required. Usage: dss recipe create --type TYPE [--input DS] (--output DS | --output-folder FOLDER_ID)");
-            }
-            if (outputFolder && !f["output-connection"]) {
-                throw new UsageError("--output-connection is required when using --output-folder.");
-            }
-            const name = f["name"];
-            const pk = f["project-key"];
-            const inputDatasets = recipeInputDatasetsFromFlags(f);
-            const joinColumns = splitCsvFlag(f["join-on"]);
-            const fuzzyColumns = splitCsvFlag(f["fuzzy-on"]);
-            const rawFuzzyDistance = f["fuzzy-distance"];
-            let fuzzyDistance;
-            if (typeof rawFuzzyDistance === "string") {
-                const normalized = rawFuzzyDistance.trim().toUpperCase();
-                if (![
-                    "DAMERAU_LEVENSHTEIN",
-                    "HAMMING",
-                    "JACCARD",
-                    "COSINE",
-                    "EUCLIDEAN",
-                ].includes(normalized)) {
-                    throw new UsageError("--fuzzy-distance must be one of DAMERAU_LEVENSHTEIN, HAMMING, JACCARD, COSINE, or EUCLIDEAN.", "invalid_enum");
-                }
-                fuzzyDistance = normalized;
-            }
-            const fuzzyThreshold = num(f["fuzzy-threshold"], "--fuzzy-threshold");
-            const payload = {
-                type,
-                name,
-                inputDatasets,
-                outputDataset,
-                outputFolder,
-                outputConnection: f["output-connection"],
-                ...(joinColumns.length > 0 ? { joinOn: joinColumns, } : {}),
-                ...(typeof f["join-type"] === "string" ? { joinType: f["join-type"], } : {}),
-                ...(fuzzyColumns.length > 0 ? { fuzzyOn: fuzzyColumns, } : {}),
-                ...(fuzzyDistance ? { fuzzyDistance, } : {}),
-                ...(fuzzyThreshold !== undefined ? { fuzzyThreshold, } : {}),
-                fuzzyNormalize: f["normalize"] === true,
-                projectKey: pk,
-            };
+            const payload = recipeCreateOptionsFromFlags(f);
+            const name = payload.name;
+            const pk = payload.projectKey;
             const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
             const zoneMove = zoneId && name
                 ? [{ objectId: name, objectType: "RECIPE", },]
@@ -312,7 +312,6 @@ export const recipeCommands = {
                 },], pk);
             return { created: createdName, resource: "recipe", ...created, ...moved, };
         },
-        usage: "dss recipe create --type TYPE [--input DS[,DS2]] (--output DS | --output-folder FOLDER_ID) [--name NAME] [--output-connection CONN] [--zone ZONE|--zone-id ID] [--if-not-exists] [--dry-run] [--join-on COL|LEFT=RIGHT[,...]] [--join-type LEFT|INNER|RIGHT|FULL] [--fuzzy-on COL|LEFT=RIGHT[,...]] [--fuzzy-distance DAMERAU_LEVENSHTEIN|HAMMING|JACCARD|COSINE|EUCLIDEAN] [--fuzzy-threshold N] [--normalize] [--project-key KEY]",
         description: "Create a recipe with optional inputs and a dataset or managed-folder output.",
         examples: [
             "dss recipe create --type python --input raw_orders,lookup --output orders_clean",
@@ -322,7 +321,7 @@ export const recipeCommands = {
     },
     clone: {
         handler: async (c, a, f) => {
-            const usage = "dss recipe clone (source|--from SOURCE) (--name NAME|--to NAME) [--replace-input FROM=TO] [--replace-output FROM=TO] [--replace-payload-text FROM=TO] [--output DATASET] [--copy-output-settings] [--path PATH] [--metastore-table TABLE] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("recipe", "clone");
             const fromFlag = typeof f["from"] === "string" ? f["from"].trim() : "";
             const sourceName = a[0] ?? fromFlag;
             if (!sourceName) {
@@ -390,7 +389,6 @@ export const recipeCommands = {
             const moved = await moveCreatedItemsToZone(c, f, [{ objectId: name, objectType: "RECIPE", },], pk);
             return { ...cloned, resource: "recipe", ...moved, };
         },
-        usage: "dss recipe clone (source|--from SOURCE) (--name NAME|--to NAME) [--replace-input FROM=TO] [--replace-output FROM=TO] [--replace-payload-text FROM=TO] [--output DATASET] [--copy-output-settings] [--path PATH] [--metastore-table TABLE] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]",
         description: "Clone a recipe graph/settings/payload into a separate experiment recipe.",
         examples: [
             "dss recipe clone compute_orders --name compute_orders_opt --output orders_opt --copy-output-settings --dry-run",
@@ -399,10 +397,10 @@ export const recipeCommands = {
     },
     diff: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss recipe diff <name> --file PATH");
+            requireArgs(a, 1, commandUsage("recipe", "diff"));
             const filePath = f["file"];
             if (!filePath) {
-                throw new UsageError("--file is required. Usage: dss recipe diff <name> --file PATH");
+                throw new UsageError(`--file is required. Usage: ${commandUsage("recipe", "diff")}`);
             }
             // Read and validate the local file before any DSS request.
             const localContent = readRecipeFile(filePath, "--file");
@@ -411,20 +409,19 @@ export const recipeCommands = {
                 projectKey: f["project-key"],
             });
             if (!result.payload) {
-                throw new Error(`Recipe "${a[0]}" has no code payload to diff.`);
+                throw new ClientValidationError(`Recipe "${a[0]}" has no code payload to diff.`, "validation_failed");
             }
             return formatLineDiff(a[0], filePath, result.payload, localContent);
         },
-        usage: "dss recipe diff <name> --file PATH [--project-key KEY]",
         description: "Show differences between local file and remote recipe code.",
         examples: ["dss recipe diff compute_orders --file code.py",],
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin]");
+            requireArgs(a, 1, commandUsage("recipe", "update"));
             const data = jsonInput(f);
             if (!data) {
-                throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin]");
+                throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${commandUsage("recipe", "update")}`);
             }
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -442,7 +439,6 @@ export const recipeCommands = {
             await c.recipes.update(a[0], data, pk);
             return { updated: a[0], resource: "recipe", };
         },
-        usage: "dss recipe update <name> (--data '{...}' | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
         description: "Update recipe settings via JSON merge. Recipe definition fields must be nested under a top-level recipe key.",
         examples: [
             "dss recipe update compute_orders --data-file settings.json --dry-run",
@@ -452,7 +448,7 @@ export const recipeCommands = {
     },
     "add-input": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss recipe add-input <recipe> <dataset> [--role ROLE] [--if-not-exists] [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("recipe", "add-input"));
             const role = f["role"] ?? "main";
             const pk = f["project-key"];
             const { recipe, } = await c.recipes.get(a[0], { projectKey: pk, });
@@ -480,7 +476,6 @@ export const recipeCommands = {
             await c.recipes.update(a[0], { recipe: { inputs: { [role]: { items: nextItems, }, }, }, }, pk);
             return { updated: a[0], resource: "recipe", action: "add-input", role, dataset: a[1], inputs, };
         },
-        usage: "dss recipe add-input <recipe> <dataset> [--role ROLE] [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Add a dataset as a recipe input by appending one item to the current inputs (no need to resend the whole list).",
         examples: [
             "dss recipe add-input compute_orders extra_lookup",
@@ -489,7 +484,7 @@ export const recipeCommands = {
     },
     "remove-input": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss recipe remove-input <recipe> <dataset> [--role ROLE] [--if-exists] [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("recipe", "remove-input"));
             const role = f["role"] ?? "main";
             const pk = f["project-key"];
             const { recipe, } = await c.recipes.get(a[0], { projectKey: pk, });
@@ -524,7 +519,6 @@ export const recipeCommands = {
                 inputs,
             };
         },
-        usage: "dss recipe remove-input <recipe> <dataset> [--role ROLE] [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Remove a dataset from a recipe's inputs by dropping one item from the current inputs.",
         examples: [
             "dss recipe remove-input compute_orders stale_lookup",
@@ -533,7 +527,7 @@ export const recipeCommands = {
     },
     "get-payload": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss recipe get-payload <name>");
+            requireArgs(a, 1, commandUsage("recipe", "get-payload"));
             const payload = await c.recipes.getPayload(a[0], {
                 projectKey: f["project-key"],
             });
@@ -543,7 +537,6 @@ export const recipeCommands = {
             }
             return payload;
         },
-        usage: "dss recipe get-payload <name> [--output PATH] [--project-key KEY]",
         description: "Print the recipe code payload as a JSON string, or write it to a file with --output.",
         examples: [
             "dss recipe get-payload compute_orders",
@@ -552,18 +545,17 @@ export const recipeCommands = {
     },
     cat: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss recipe cat <name>");
+            requireArgs(a, 1, commandUsage("recipe", "cat"));
             return c.recipes.getPayload(a[0], {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss recipe cat <name> [--project-key KEY]",
         description: "Print the recipe code payload as a JSON string.",
         examples: ["dss recipe cat compute_orders",],
     },
     "set-payload": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss recipe set-payload <name> --file PATH");
+            requireArgs(a, 1, commandUsage("recipe", "set-payload"));
             const filePath = f["file"];
             if (!filePath)
                 throw new UsageError("--file is required.");
@@ -603,7 +595,6 @@ export const recipeCommands = {
                 ...(backupPath ? { backupPath, } : {}),
             };
         },
-        usage: "dss recipe set-payload <name> --file PATH [--backup-dir DIR|--no-backup] [--dry-run] [--project-key KEY]",
         description: "Upload recipe code from a local file, backing up payload, graph, settings, and version metadata by default.",
         examples: [
             "dss recipe set-payload compute_orders --file code.py --dry-run",
@@ -613,7 +604,7 @@ export const recipeCommands = {
     },
     restore: {
         handler: async (c, a, f) => {
-            const usage = "dss recipe restore <name> --backup FILE [--payload-only] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("recipe", "restore");
             requireArgs(a, 1, usage);
             const backupPath = requiredStringFlag(f, "backup", usage);
             const backup = readRecipeBackupFile(backupPath);
@@ -648,7 +639,6 @@ export const recipeCommands = {
                 payloadOnly: f["payload-only"] === true,
             };
         },
-        usage: "dss recipe restore <name> --backup FILE [--payload-only] [--dry-run] [--project-key KEY]",
         description: "Restore a recipe from a set-payload backup.",
         examples: [
             "dss recipe restore compute_orders --backup .dss-backups/recipes/backup.recipe-backup.json --dry-run",
@@ -656,7 +646,7 @@ export const recipeCommands = {
     },
     "assert-unchanged": {
         handler: async (c, a, f) => {
-            const usage = "dss recipe assert-unchanged <name> --since BACKUP [--project-key KEY]";
+            const usage = commandUsage("recipe", "assert-unchanged");
             requireArgs(a, 1, usage);
             const backupPath = requiredStringFlag(f, "since", usage);
             const backup = readRecipeBackupFile(backupPath);
@@ -708,10 +698,9 @@ export const recipeCommands = {
                 failures,
             };
         },
-        usage: "dss recipe assert-unchanged <name> --since BACKUP [--project-key KEY]",
         description: "Compare current recipe payload, graph, and code env against a backup.",
         examples: [
             "dss recipe assert-unchanged compute_orders --since .dss-backups/recipes/backup.recipe-backup.json",
         ],
     },
-};
+});